Wikibooks:Requests for deletion

<mediawiki xmlns="http://www.mediawiki.org/xml/export-0.11/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mediawiki.org/xml/export-0.11/ http://www.mediawiki.org/xml/export-0.11.xsd" version="0.11" xml:lang="en">
  <siteinfo>
    <sitename>Wikibooks</sitename>
    <dbname>enwikibooks</dbname>
    <base>https://en.wikibooks.org/wiki/Main_Page</base>
    <generator>MediaWiki 1.47.0-wmf.19</generator>
    <case>first-letter</case>
    <namespaces>
      <namespace key="-2" case="first-letter">Media</namespace>
      <namespace key="-1" case="first-letter">Special</namespace>
      <namespace key="0" case="first-letter" />
      <namespace key="1" case="first-letter">Talk</namespace>
      <namespace key="2" case="first-letter">User</namespace>
      <namespace key="3" case="first-letter">User talk</namespace>
      <namespace key="4" case="first-letter">Wikibooks</namespace>
      <namespace key="5" case="first-letter">Wikibooks talk</namespace>
      <namespace key="6" case="first-letter">File</namespace>
      <namespace key="7" case="first-letter">File talk</namespace>
      <namespace key="8" case="first-letter">MediaWiki</namespace>
      <namespace key="9" case="first-letter">MediaWiki talk</namespace>
      <namespace key="10" case="first-letter">Template</namespace>
      <namespace key="11" case="first-letter">Template talk</namespace>
      <namespace key="12" case="first-letter">Help</namespace>
      <namespace key="13" case="first-letter">Help talk</namespace>
      <namespace key="14" case="first-letter">Category</namespace>
      <namespace key="15" case="first-letter">Category talk</namespace>
      <namespace key="102" case="first-letter">Cookbook</namespace>
      <namespace key="103" case="first-letter">Cookbook talk</namespace>
      <namespace key="108" case="first-letter">Transwiki</namespace>
      <namespace key="109" case="first-letter">Transwiki talk</namespace>
      <namespace key="110" case="first-letter">Wikijunior</namespace>
      <namespace key="111" case="first-letter">Wikijunior talk</namespace>
      <namespace key="112" case="first-letter">Subject</namespace>
      <namespace key="113" case="first-letter">Subject talk</namespace>
      <namespace key="710" case="first-letter">TimedText</namespace>
      <namespace key="711" case="first-letter">TimedText talk</namespace>
      <namespace key="828" case="first-letter">Module</namespace>
      <namespace key="829" case="first-letter">Module talk</namespace>
      <namespace key="1728" case="first-letter">Event</namespace>
      <namespace key="1729" case="first-letter">Event talk</namespace>
    </namespaces>
  </siteinfo>
  <page>
    <title>Wikibooks:Requests for deletion</title>
    <ns>4</ns>
    <id>385</id>
    <revision>
      <id>4669789</id>
      <parentid>4669229</parentid>
      <timestamp>2026-09-13T02:20:17Z</timestamp>
      <contributor>
        <username>1234qwer1234qwer4</username>
        <id>1406991</id>
      </contributor>
      <comment>/* Chess Opening Theory/1. g4/1...Na6 */ new topic ([[mw:c:Special:MyLanguage/User:JWBTH/CD|CD]])</comment>
      <origin>4669789</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="43534" sha1="oul17jw5p7mzhjt395h0z97cdu5cgk5" xml:space="preserve">__NEWSECTIONLINK__
[[Category:Wikibooks deletion|{{PAGENAME}}]]
{{Discussion Rooms}}
{{TOCleft}}
{{shortcut|WB:RFD}}
{{Requests for deletion/New deletion}}
{{Requests for deletion/Deletion intro}}
&lt;!-- New deletion nominations go at the bottom of page. --&gt;

== [[Salute, Jonathan!]] and its translations ==

&lt;div style=&quot;column-count: 7;&quot;&gt;
* [[Salute, Jonathan!|Interlingue/Occidental]] ([[w:en:Occidental|w]], original)
* [[Òla, Ionatà!|Audià]]
* [[Holo, Jonathan!|Cristianés]]
* [[Terve, Jonathan!|Ekumenski]]
* [[Hej, Jonathan! (Germanisch)|Germanisch]]
* [[Salom, Jonatan!|Globasa]]
* [[Àlŏ, Jonathan!|Guosa]] ([[w:en:Guosa|w]])
* [[Salut, Jonathan!|Idiom Neutral]] ([[w:en:Idiom Neutral|w]])
* [[Saluto, Jonathan! (Ido)|Ido]] ([[w:en:Ido|w]])
* [[Hallo, Jonathan!|Interlingua]] ([[w:en:Interlingua|w]])
* [[Salut, Jonathan! (Interocidental)|Interocidental]]
* [[Bune Ğonatan!|Lingaust]]
* [[Oila, Jonatan!|Lingue Simple]]
* [[Haloo, Jonatan!|Lingwa de Planeta]] ([[w:en:Lingwa de Planeta|w]])
* [[Sin Chao, Jonathan!|Masa Tang]]
* [[Salut, ionatano!|Meteza]]
* [[Salu, Jon!|Mini]]
* [[Hay, Jonathan!|Mirad]]
* [[Hai, Jon!|Monav]]
* [[Sesan Jon!|Monkel]]
* [[Salam, Jonathan!|Mundeze]]
* [[Dag, Jonathan!|Negerhollands]] ([[w:en:Negerhollands|w]])
* [[Salut Jonathan!|Neo]] ([[w:en:Neo|w]])
* [[Hej, Jonathan!|Nordien]]
* [[Saluto, Jonathan!|Novial]] ([[w:en:Novial|w]])
* [[Salute, Jonathan! (Novlingue)|Novlingue]]
* [[Alo, Jonathan!|Numo]]
* [[Hela, Jonathan!|Proyo]]
* [[Salute, Jonathan! (Romanica)|Romanica]] ([[w:en:Romanica|w]])
* [[Simi, Jonathan!|Solresol]] ([[w:en:Solresol|w]])
* [[Toki a, jan Jonatan!|Toki Pona]] ([[w:en:Toki Pona|w]])
* [[Glidis, o Jonathan!|Volapük]] ([[w:en:Volapük|w]])
&lt;/div&gt;

There are a couple of issues here:

# Beyond their introductions, all of these books are written in languages which are not English, making them out of scope for the English Wikibooks.
# All but one of these books are in fact written in constructed languages, most of them in recently created conlangs. In some cases (e.g. [[Sin Chao, Jonathan!]]), I can't find any reliable sources describing the target language outside of the translation itself.
# Most of the translations (i.e. other than [[Salute, Jonathan!]] itself) were abandoned within the first five or so chapters (out of 100); none of them are complete, and there seems to be little effort to complete any of them.

While I recognize that this is an unusual project, and potentially one which could have some value, it's not at all clear to me that the English Wikibooks is the right place for it. — [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 00:24, 29 September 2024 (UTC)

: I'm really not sure what to do about these ones. While I recognize that this approach is certainly one method of teaching a language, I'm not sure that it constitutes an educational textbook. We do require that the English Wikibooks be written in English—for language-learning books, this typically means that the instructional parts are in English while the exercises are in the language being taught. I do think that if the language doesn't have much supporting evidence outside the book itself, it can safely be deleted. — [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 01:01, 29 September 2024 (UTC)

: Author of the book here. I originally wanted to put it in the Interlingue Wikibooks https://ie.wikibooks.org/wiki/Principal_p%C3%A1gine but it somehow got locked when I wasn't paying attention and so I ended up putting it here. Getting it unlocked requires going through the process of starting an Incubator and all the rest so I opted for here and then started putting some English-only content once it was done. It's sort of in the same vein as books like Lingua Latina per se Illustrata that have separate versions with teacher notes and whatnot. [[Salute, Jonathan!/Capitul 1 - with notes]] After it was done the auxlang community really took to it which was a nice surprise. I think Ido has the largest number of chapters at the moment at 15.
:If the vast content of this book could be used to justify a quick reopening of the Interlingue Wikibooks to move it there, I'd love to do that. I imagine that an incubator with 100+ book chapters would be enough to open a Wikibooks and that's what this is. — [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 06:02, 29 September 2024 (UTC)

: Ah, I just realized that we do have a proposal to reopen the Interlingue Wikibooks: https://meta.wikimedia.org/wiki/Requests_for_new_languages/Wikibooks_Interlingue along with an Incubator page here. https://incubator.wikimedia.org/wiki/Wb/ie/Principal_p%C3%A1gine
: How easy would it be to migrate the entirety of Salute Jonathan to there? — [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 06:30, 29 September 2024 (UTC)

:: Hi @[[User:Mithridates|Mithridates]]! I'm not sure how incubator projects work, but I fully support migrating these books there. You may want to inquire over there and link to this discussion to support your request to move the content over there. Cheers! — [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 13:16, 29 September 2024 (UTC)

::: Hi! Actually I have a third idea to propose after thinking about this again today (haven't been here much since I finished the book): I noticed that there is more English content than I remember and that might make it an awkward fit for the Interlingue Wikibooks. I definitely agree that having all the auxlang translations for new auxlang projects goes well beyond the scope of this Wikibooks. Finally, there are some auxlangs that are notable with their own Wikipedias.
::: So the idea is the following:
:::# Leave the original here and I can continue the work on the version with English notes and grammar. That will make it the same as Lingua Latina per se Illustrata, English by the Nature Method, Athenaze and all the rest.
:::# The Interlingua one can move to the Interlingua Wikibooks (maybe Romanica too if they want as it is sort of a dialect of Interlingua).
:::# For Ido and Lingua Franca Nova which have a Wikipedia but not a Wikibooks, I'm a little bit unsure...technically they could have their own version like the original one but would require English explanations. I could let them know and see if they are willing to do so and see what they think (work on adding English to the books vs. move the content elsewhere).
:::# The rest can move to a Github repo, then be deleted, and the front page of this book can have a single link to the repo.
::: Any thoughts on that? Adding the extra English content will be easy as it is my book and I know it inside and out.
::: Edit: [https://en.wikibooks.org/wiki/Salute,_Jonathan!/Grammar_(pronouns) this page] I just added.  — [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 13:50, 29 September 2024 (UTC)

:::: Thanks for taking the time to consider this! Here are my responses/questions:
::::* Is the original [[Salute, Jonathan!]] (Occidental)? Since that one is quite fleshed out, I agree that if you edit it so the primary language of the book (e.g. headers, instructions, etc) are written in English while leaving the actual story in Occidental, it would be okay and fit in more with instructional language textbooks.
::::* For your points 2 and 3, I'm not sure how those other projects work, so I'll leave it up to them. I'm not quite sure why they would need to move, since in theory they could be revised with English as the language of instruction? Although, they have been left incomplete for a long time.
::::* For your point 4, I have no problem with that. Cheers! — [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 16:51, 29 September 2024 (UTC)

::::: Hello again, it's the weekend so I have a bit more time to work on this. I've decided to merge the extra content from the following five chapters since the difference is fairly small and the original chapters should now have this English content. Could you delete these five pages now that they are no longer needed? [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 14:02, 5 October 2024 (UTC)
::::: [[Salute, Jonathan!/Capitul 1 - with notes]]
::::: [[Salute, Jonathan!/Capitul 2 - with notes]]
::::: [[Salute, Jonathan!/Capitul 3 - with notes]]
::::: [[Salute, Jonathan!/Capitul 4 - with notes]]
::::: [[Salute, Jonathan!/Capitul 5 - with notes]] [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 14:02, 5 October 2024 (UTC)
:::::: [[File:Yes_check.svg|{{#ifeq:|small|8|15}}px|link=|alt=]] {{#ifeq:|small|&lt;small&gt;|}}'''Done'''{{#ifeq:|small|&lt;/small&gt;|}} — [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 23:34, 5 October 2024 (UTC)

::::::: Hi again! No luck trying to find a home for the random language translations on other auxlang wikis, can't find one that is actively maintained.
::::::: The thought struck me that maybe I could just put those ones on a sub page of my user page, would that be permitted? If not, I think I'll just stick them somewhere in GitHub and call it a day since none of the people who started the translations seem to care enough to do anything about them. I'd rather not see them outright disappear but since they aren't mine I don't care enough about them to do much more work than copy and paste them somewhere.
::::::: (I would leave the ones in languages with an ISO-639 code and Wikipedia here, of course) — [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 14:13, 9 November 2024 (UTC)

:::::::: Thank you for checking! I don't personally see an issue with moving them to your user space right now. Cheers — [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 17:21, 9 November 2024 (UTC)

::::::::: Thanks a lot! I've started a single page where I will put them all here [[User:Mithridates/SJ]] and will proceed slowly due to lack of time and also to avoid stepping on any toes / asking you to delete too much at a time and possibly deleting the wrong content.
::::::::: For this week I have put the content for the languages Audia, Cristianès, Guosa, Lingaust, Mini, Mirad, and Monav on that page as they all have a single page of content and didn't take much time to move. Please delete those. Once they are gone I will add a note on the main page letting people know where they have gone (in addition to a thank you for their interest in the book! I do love how many people have recognized it as a good source material for teaching a language). — [[User:Mithridates|Mithridates]] ([[User talk:Mithridates|discuss]] • [[Special:Contributions/Mithridates|contribs]]) 04:09, 10 November 2024 (UTC)

: {{keep}} the translations for languages that have an article on the English Wikipedia, i.e. Guosa, Idiom Neutral, Ido, Interlingua, Lingwa de Planeta, Negerhollands, Neo, Novial, Occidental, Romanica, Solresol, Toki Pona, and Volapük.
: Translations for languages that don't have an article can be kept if they have reliable sources, which I was able to find for the following languages (if you think they are not reliable, please let me know):
:* Globasa: [https://www.languagesandnumbers.com/how-to-count-in-globasa/en/globasa/] [https://greyson.conlang.org/2020/01/29/shouting-out-globasa-and-pandunia/]
:* Mini: [https://jprogr.github.io/mini] [https://www.omniglot.com/language/phrases/mini.htm] [https://www.languagesandnumbers.com/how-to-count-in-mini/en/mini/]
: {{del}} and move to [[User:Mithridates/SJ]] the rest of the translations, i.e. Audià/Audian, Cristianés, Ekumenski, Germanisch, Interocidental, Lingaust, Lingue Simple, Masa Tang, Mirad, Monav, Monkel, Mundeze, Nordien, Novlingue, Numo, Proyo, and Scuian/Meteza. If you can find reliable sources for those languages, please let me know.
: In particular, I could not find resources for Audià/Audian and Monav after searching through 15 and 17 pages on Google, respectively. It doesn't help that [[Òla, Ionatà!|their]] [[Hai, Jon!|translations]] don't explain what those languages are and where to find resources for them. This makes contributing to those translations almost impossible until @[[User:Caro de Segeda|Caro de Segeda]] can provide resources to us. It's possible that the resources may have disappared from the Internet, or that those languages were created by Caro de Segeda him/herself. If you can find resources for Audià/Audian and Monav, please let me know.
: I'm notifying the primary contributors of the translations: @[[User:Caro de Segeda|Caro de Segeda]], @[[User:Frzzl|Frzzl]], @[[User:Greatscotteh|Greatscotteh]], @[[User:IHateNumbers234|IHateNumbers234]], @[[User:Jayeless2|Jayeless2]], @[[User:Morozof|Morozof]], @[[User:Omnihom|Omnihom]], @[[User:Omoutuazn|Omoutuazn]], @[[User:PovriNaivon|PovriNaivon]], @[[User:Sir Beluga|Sir Beluga]] and @[[User:Tyoyafud|Tyoyafud]]. — [[User:EJPPhilippines|EJPPhilippines]] ([[User talk:EJPPhilippines|discuss]] • [[Special:Contributions/EJPPhilippines|contribs]]) 09:52, 30 June 2025 (UTC)

:: Caro de Segeda said on [https://www.reddit.com/r/conlangs/comments/1lcnz9g/comment/n0sc3wx/ Reddit] that Monav was created by him/her and that he/she didn't publish any resources about it other than [[Hai, Jon!]]. With '''zero''' other resources to rely on for contributing to the translation, and the fact that Monav is in [[User:Mithridates/SJ]], [[Hai, Jon!]] should be speedy deleted. — [[User:EJPPhilippines|EJPPhilippines]] ([[User talk:EJPPhilippines|discuss]] • [[Special:Contributions/EJPPhilippines|contribs]]) 01:38, 3 July 2025 (UTC)

::: I've undone the speedy deletion as Caro de Segeda posted a [https://prexins.wordpress.com/2025/07/04/monav/ resource] for Monav. — [[User:EJPPhilippines|EJPPhilippines]] ([[User talk:EJPPhilippines|discuss]] • [[Special:Contributions/EJPPhilippines|contribs]]) 07:18, 4 July 2025 (UTC)

:::: You can delete all the ones that I have created myself, I have already moved them to other places. — [[User:Caro de Segeda|Caro de Segeda]] ([[User talk:Caro de Segeda|discuss]] • [[Special:Contributions/Caro de Segeda|contribs]]) 12:39, 5 July 2025 (UTC)

{{outdent|::::}}I don't know if this is helpful since it wouldn't apply to most of these, but [[s:mul:]] could hold some of these. — [[User:Arlo Barnes|Arlo Barnes]] ([[User talk:Arlo Barnes|discuss]] • [[Special:Contributions/Arlo Barnes|contribs]]) 09:18, 30 November 2025 (UTC)

: I don't think that would be within the scope of that project. I'm not aware of any other situation where Wikisource publishes translations of texts created on Wikimedia projects - that's usually left up to other language editions of the same project. — [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 05:34, 1 December 2025 (UTC)

:: In this situation there isn't a separate [[s:ie:]] distinct from Multilingual Wikisource (see [[meta:Wikisource#List of Wikisources]]). In fact, there are very few multilingual wikis in the Wikimedia sphere; while this project ''could'' move to a Miraheze-hosted or similar wiki farm location, I think it would be a missed opportunity. I suppose an [[Interlingue]] book could be started in [[shelf:Constructed languages]] which would have all 100 chapters as an appendix (and likewise for the other languages), but that also seems non-ideal since it requires an English-language text that doesn't currently exist to be created. [[WB:AT]] seems to describe a similar situation to this one and prescribe Wikisource as the solution, and [[WB:SOURCE]] mentions fiction as out-of-scope for Wikibooks (even as in this case, language-educational fiction). [[s:mul:Wikisource:about Wikisource]] simply speaks of source texts and doesn't mention publication requirements, so maybe that is specific to some of the monolingual editions? — [[User:Arlo Barnes|Arlo Barnes]] ([[User talk:Arlo Barnes|discuss]] • [[Special:Contributions/Arlo Barnes|contribs]]) 22:28, 5 December 2025 (UTC)

:{{keep}} 100% keep. These books are a core part of language textbooks on Wikibooks and have been for years. Not sure why this is even being debated.--[[User:Xania|Xania]] [[Image:Flag_of_Estonia.svg|15px]]  [[Image:Flag_of_Ukraine.svg|15px]] [[User talk:Xania|&lt;sup&gt;talk&lt;/sup&gt;]] 17:55, 16 May 2026 (UTC)

::With all due respect, some of the books included in this nomination (like [[Sin Chao, Jonathan!]]) are written in constructed languages which are not substantially attested anywhere else. I struggle to imagine any educational purpose for such a book. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 00:12, 17 May 2026 (UTC)

== [[International Baccalaureate]] ==

Not actually a book in and of itself; rather, it is just a compilation of links to other books —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 23:24, 18 October 2024 (UTC)
: Could this be salvaged as a shelf? [[User:Pppery|Pppery]] ([[User talk:Pppery|discuss]] • [[Special:Contributions/Pppery|contribs]]) 05:23, 27 January 2025 (UTC)
::Probably, but are the linked books even useful? IB exams change from year to year - sometimes quite dramatically - so an old exam guide is of very limited value. Many of these books were written 10-15 years ago, and some of them (like [[IB French]]) even have comments indicating that they're no longer applicable. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 02:18, 8 December 2025 (UTC)

== [[Character List for Baxter&amp;Sagart]] ==

Seems completely out of scope as an educational book; it's just a list of characters and outlinks —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 23:53, 18 October 2024 (UTC)

:Adding [[Character List for Karlgren's GSR]] and [[Character List for Schuessler's CGSR]] for the same reason —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 23:55, 18 October 2024 (UTC)

:These three books do make a package and I agree they should be considered together. However, I strongly object to deleting them. They are really extremely useful resources. I use them every week and I know that many people who do work on Old Chinese phonology do so. There are lots of books out there that are lists of characters, these are called dictionaries. For example Axel Schuessler's ABC Etymological Dictionary of Old Chinese, or Pulleyblank's Lexicon of Reconstructed Pronunciation in Early Middle Chinese, Late Middle Chinese, and Early Mandarin. I see it as entirely a good thing for reference works of this kind to be available free online rather than only in expensive books in university research libraries. If this is in violation of a Wikibooks policy, I would at least like that policy to be drawn to my attention and to have some constructive comment offered about which Wikiproject such a resource should fall under. I will also say on a personal note that I have put literally hundreds of hours of work into these projects and it would grieve me a lot to see this work simply vanish, in particular when I know that colleagues around the world use these books. --[[User:Tibetologist|Tibetologist]] ([[User talk:Tibetologist|discuss]] • [[Special:Contributions/Tibetologist|contribs]]) 07:27, 1 November 2024 (UTC)
::Hi @[[User:Tibetologist|Tibetologist]], and thank you for the feedback! Official Wikibooks policy does not permit standalone dictionaries (see [[WB:DICT]]), though I understand the argument that it is a useful resource. I am wondering if there might be a home for it at [[Wiktionary:Wiktionary:Welcome, newcomers|Wiktionary]] or [[Wikiversity:Wikiversity:SHARE|Wikiversity]]? Cheers —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 12:14, 1 November 2024 (UTC)
:::The policy says to use Wiktionary, but these books cannot be moved there. In fact they link there, you can understand me as having made an index to wiktionary, if you like, where the ORDER of the characters is extremely important, information that would be lost in Wiktionary. 
:::Wikiversity is not a project I participate in, and in any event my books here are older than it, so this option was not available for me at the relevant moment. If you are offering to move my books to Wikiversity, that is very kind of you and I will very graciously accept. [[User:Tibetologist|Tibetologist]] ([[User talk:Tibetologist|discuss]] • [[Special:Contributions/Tibetologist|contribs]]) 14:10, 1 November 2024 (UTC)
::::I have pinged over at Wikiversity Colloquium to ask about suitability and have looped you into the conversation over there. Cheers —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 18:20, 1 November 2024 (UTC)
::I concur. I'm just an undergrad who tries to learn about Sino-Tibetan historical linguistics in his free time but I've found this wikibook to be incredibly useful, and I keep it open in one tab while I watch Professor Nathan Hill's lectures that he uploads to youtube in another tab, and another tab for taking notes. In fact if I remember correctly Professor Hill actually pointed his students to this wikibook. 
::I'm not familiar with [[wikiversity:Wikiversity:SHARE|Wikiversity]] but if all the content were as accessible there as it is here then I think that could work.  [[User:ChromeBones|ChromeBones]] ([[User talk:ChromeBones|discuss]] • [[Special:Contributions/ChromeBones|contribs]]) 02:43, 9 July 2025 (UTC)
:Per [[:v:Wikiversity:Colloquium#Import_Resource_From_Wikibooks?]], I recommend copying and pasting, including attribution via the edit summary and talk page, add appropriate categories and links, and then it could be deleted locally. —[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''vf&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 22:32, 3 November 2024 (UTC)

== [[Suomen kieli käyttöön]] ==

Multiple pages in this book are written entirely in Finnish, which is out of the enWB scope. —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 00:09, 19 October 2024 (UTC)

:I was going to say whether we should ask any fiwikibooks sysop to maybe see if this could be transwikied to fiwb if it's within the scope there. But [[:fi:Toiminnot:Käyttäjät/sysop]] indicates that there are only 3 sysops, and only {{u|Anr}} and {{u|Zache}} have made edits this ''year''. If they deem it to be salvageable, then transwiki + delete, otherwise straight-up delete. --[[User:SHB2000|SHB2000]] ([[User talk:SHB2000|discuss]] • [[Special:Contributions/SHB2000|contribs]]) 11:24, 14 November 2024 (UTC)
::It seems that the idea behind the book was for the pages to be bilingual, as it’s a language learning book. That’s why there are Finnish texts included intentionally even on the pages that are complete. There are similar books in dewikibooks and ruwikibooks as well. For the English version, I think the easiest way to proceed would be to clean up and adjust the page layout to fit enwikibooks better, and then translate the missing parts. By the way, if anyone wants to update the book’s name in English, it can be titled ''&quot;Using the Finnish Language&quot;'' or ''&quot;Put Finnish Language into Use&quot;'' for a direct translation.   [[User:Zache|Zache]] ([[User talk:Zache|discuss]] • [[Special:Contributions/Zache|contribs]]) 11:57, 14 November 2024 (UTC)

== [[AT&amp;T Mobility FAQ]] ==

* [[AT&amp;T Mobility FAQ]]
* [[AT&amp;T Mobility FAQ/MEdia Net Configuration]]
* [[AT&amp;T Mobility FAQ/Data Connect Configuration]]
An ''extremely'' outdated FAQ on AT&amp;T's cell phone services. Most of this document was written 20+ years ago as a Usenet FAQ; very little of it is accurate or useful anymore (particularly the two subpages, which have to do with obsolete configurations for &quot;tethering&quot; a computer to a cell phone). No objection if someone wants to update it, but there's clearly been no appetite to do that. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 22:20, 30 December 2024 (UTC)

:I'm wondering if it might make sense for us to develop some kind of policy on archiving books here. There are many like this one that have a good deal of content but are extremely out of date and just not useful as originally intended. ——[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 22:34, 30 December 2024 (UTC)
::@[[User:Kittycataclysm|Kittycataclysm]]: See the newly developed [[Wikibooks:Outdated books]]. [[User:JJPMaster|JJP]]&lt;sub&gt;[[User talk:JJPMaster|Mas]]&lt;sub&gt;[[Special:Contributions/JJPMaster|ter]]&lt;/sub&gt;&lt;/sub&gt; ([[wikt:she|she]]/[[wikt:they|they]]) 00:16, 31 December 2024 (UTC)
:::Ooh, thanks - something like that seems like it could be an appropriate way to handle this book. A lot of the other outdated books I've tagged have been so incomplete that they wouldn't have been particularly useful even as historical references; this one might at least have some interest.
:::Any chance we can get a separate namespace (maybe &quot;Archive:&quot;) set up for archived book content? That'd make it possible to do things like exclude them from on-site search by default. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 21:07, 31 December 2024 (UTC)
::::I think this might be a more extended discussion, so I'll bump it over to the [[Wikibooks talk:Outdated books|talk page of the draft policy]]! —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 21:54, 31 December 2024 (UTC)

== Algebra/Chapter 10/Symmetric Polynomials ==

I personally believe that [[Algebra/Chapter 10/Symmetric Polynomials|this]], and all of the sections should be deleted for the fact that this goes WAY beyond the scope of what was intended for the Chapter (Algebra II level polynomials). [[User:GoreyCat|GoreyCat]] ([[User talk:GoreyCat|discuss]] • [[Special:Contributions/GoreyCat|contribs]]) 15:07, 6 February 2025 (UTC)

:'''Split''': Deletion here is not the best solution (see [[w:WP:ATD]]). Instead, this page and its subpages should be moved to another book, most likely [[Abstract Algebra]]. [[User:JJPMaster|JJP]]&lt;sub&gt;[[User talk:JJPMaster|Mas]]&lt;sub&gt;[[Special:Contributions/JJPMaster|ter]]&lt;/sub&gt;&lt;/sub&gt; ([[wikt:she|she]]/[[wikt:they|they]]) 17:35, 6 February 2025 (UTC)
:{{keep}} since there is a good amount of content. If [[Abstract Algebra]] is appropriate, it seems like a fine idea to move there. —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 22:59, 7 February 2025 (UTC)
::Eh, yeah, I supposed moving it is better. I just don't think it's suitable for where it appears. [[User:GoreyCat|GoreyCat]] ([[User talk:GoreyCat|discuss]] • [[Special:Contributions/GoreyCat|contribs]]) 01:40, 8 February 2025 (UTC)
== [[Puredyne]] ==

Development of Puredyne Linux was discontinued in 2012, and the software no longer appears to be available for download anywhere. (An archive of the web site is still up - with a bunch of embedded spam links - but the download links are all dead.) Is this a suitable candidate for archival (cf. [[Wikibooks:Outdated books]]), or should it just be deleted? [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 04:35, 5 March 2025 (UTC)

:I'd just archive stuff like this. Looks like a decent bit of work went into it, and you never know when someone might need to use Puredyne for some obscure project. I'd be willing to bet mirrors exist of it somewhere, or someone has it on a drive. If you want to find some stuff worth deleting, comb through [[:Category:Allbooks categories]]. [[User:MediaKyle|MediaKyle]] ([[User talk:MediaKyle|discuss]] • [[Special:Contributions/MediaKyle|contribs]]) 11:30, 5 March 2025 (UTC)

== [[Template:Qr-twwp]] ==
This isn't exactly a request to delete the template, but rather to merge it with {{tlx|Copypaste}}. The {{tlx|Qr-twwp}} template serves the same purpose as {{tlx|Copypaste}}, but without the seven-day period after which the page is deleted. This leads to confusion, as well as a perpetually full [[:Category:Queried pages]]. [[User:JJPMaster|JJP]]&lt;sub&gt;[[User talk:JJPMaster|Mas]]&lt;sub&gt;[[Special:Contributions/JJPMaster|ter]]&lt;/sub&gt;&lt;/sub&gt; ([[wikt:she|she]]/[[wikt:they|they]]) 17:37, 30 March 2025 (UTC)

== [[Ghouls of the Miskatonic]] ==

I don't think that a plot summary of a book is in-scope here. —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 18:43, 20 August 2025 (UTC)

:{{vd}} - at least, not a summary of ''this'' book. A summary and/or study guide to a notable work of literature might be in scope, but this is certainly not one. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 21:23, 25 August 2025 (UTC)
::Hi. I am the creator of the pages of this book. If I understand correctly, it has to be a summary of a notable work of literature? So what exactly is defined as such? I only started this as I thought it would be fun, interesting and encouraging to others who read the Arkham Horror novels, and I thought it was permitted as I've seen other summaries of books on wikibooks. [[User:Dayne90|Dayne90]] ([[User talk:Dayne90|discuss]] • [[Special:Contributions/Dayne90|contribs]]) 13:27, 26 August 2025 (UTC)
:::Your problem is it is just the plot... it needs to include an educational textual analysis to be in scope [[User:MarcGarver|MarcGarver]] ([[User talk:MarcGarver|discuss]] • [[Special:Contributions/MarcGarver|contribs]]) 12:47, 28 August 2025 (UTC)
::::And ideally it'd be a text which has ''already'' been the subject of literary analysis, such that the analysis on Wikibooks isn't original research. A notable work of literature like ''Frankenstein'' or ''Moby-Dick'' would easily meet that requirement; a tie-in novel for a tabletop RPG probably does not. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 22:08, 29 August 2025 (UTC)

== [[Objective Projection: Why the Brain Never Forgets Some Stories]] ==

Undisclosed AI-generated content. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 02:13, 9 May 2026 (UTC)

:&lt;nowiki&gt;'''Keep'''&lt;/nowiki&gt; — Comment from page author/subject expert.
:I am Levent Bulut, the originator of the &lt;nowiki&gt;''&lt;/nowiki&gt;Objective Projection&lt;nowiki&gt;''&lt;/nowiki&gt; methodology described in this book (ORCID: 0009-0007-7500-2261, Wikidata: Q138048287). I want to address the AI-generated content concern directly and transparently.
:&lt;nowiki&gt;'''&lt;/nowiki&gt;On the content itself:&lt;nowiki&gt;'''&lt;/nowiki&gt; The methodology, theoretical framework (the six-variable operator E(r) = projS(M, T, V, Δ, Ω, Ng), the Six Golden Rules, the Six-Layer Framework), and all original arguments are my own intellectual work, developed and published independently. This is documented through:
:* 26 DOI-registered academic publications on Zenodo (search: &quot;Levent Bulut Objective Projection&quot;)
:* A peer-reviewed submission currently under review at &lt;nowiki&gt;''&lt;/nowiki&gt;Digital Humanities Quarterly&lt;nowiki&gt;''&lt;/nowiki&gt;
:* Parallel Turkish-language Wikibook and Wikiversity pages on the same methodology
:* An open-source SFT dataset on Hugging Face (leventbulut/objective-projection)
:&lt;nowiki&gt;'''&lt;/nowiki&gt;On AI assistance:&lt;nowiki&gt;'''&lt;/nowiki&gt; I used AI tools (Claude) for English translation polish and copy-editing from my Turkish source materials — the same way a non-native English-speaking academic would use a human translator or editor. The &lt;nowiki&gt;''&lt;/nowiki&gt;ideas, structure, terminology, citations, and arguments&lt;nowiki&gt;''&lt;/nowiki&gt; are entirely my own and pre-date the Wikibooks version, traceable through Zenodo DOI timestamps starting in 2025.
:&lt;nowiki&gt;'''&lt;/nowiki&gt;Proposed remedy instead of deletion:&lt;nowiki&gt;'''&lt;/nowiki&gt; I am happy to:
:# Add a clear AI-assistance disclosure to the book's preface, per Wikibooks transparency norms
:# Add inline citations to the underlying DOI-registered publications for every major claim
:# Link to the parallel Turkish version and academic record
:This would address the &lt;nowiki&gt;''&lt;/nowiki&gt;undisclosed&lt;nowiki&gt;''&lt;/nowiki&gt; part of the concern (which is the actionable policy issue) while preserving content that is original academic work by an identifiable author with a published track record. Deletion of original scholarship because translation assistance was used would set a concerning precedent for non-native English contributors.
:&lt;nowiki&gt;I request a few days to add the disclosure and citations before any deletion action. ~~~~&lt;/nowiki&gt; [[Special:Contributions/&amp;#126;2026-28847-60|&amp;#126;2026-28847-60]] ([[User talk:&amp;#126;2026-28847-60|talk]]) 18:46, 13 May 2026 (UTC)
::Administrative assistance needed: Automated filters blocking structural improvements and disclosures
::'''Request for Help''' — I am Levent Bulut, the author of this book. I have already provided my AI disclosure and academic credentials (ORCID, DOI list) here in this discussion.
::I am trying to update the book to comply with Wikibooks standards by:
::Adding a formal '''AI assistance disclosure''' at the top of the page.
::Restructuring the content into an '''instructional textbook format''' (adding Learning Objectives).
::Converting plain text formulas into '''LaTeX''' ( format).
::Updating references to include full academic '''DOI''' records.
::However, the automated filter is blocking all my attempts:
::If I try to replace the content with the improved version, it triggers the '''&quot;large amount of content removal&quot;''' filter.
::If I try to add specific academic links, it triggers the '''&quot;automated link/spam&quot;''' filter.
::I am essentially trapped by the filters while trying to improve the book and follow transparency norms. Could an administrator please either whitelist my account or manually apply the improved version of the text? I am ready to provide the full MediaWiki code here if requested. My intent is purely constructive and academic. [[Special:Contributions/&amp;#126;2026-28847-60|&amp;#126;2026-28847-60]] ([[User talk:&amp;#126;2026-28847-60|talk]]) 19:15, 13 May 2026 (UTC)
::: Hi, @[[User:~2026-28847-60|~2026-28847-60]]. Your account was incorrectly locked by a steward. It is now currently unlocked. [[User:Codename Noreste|&lt;span style=&quot;color:#0024FF&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 17:44, 15 May 2026 (UTC)
:::: Pinging @[[User:Projection Architect|Projection Architect]], who was previously LeventBulut. [[User:Codename Noreste|&lt;span style=&quot;color:#0024FF&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 15:51, 4 July 2026 (UTC)
::Please review [[Wikibooks:Artificial intelligence]]. It states unequivocally that {{tq|LLMs may not be used to generate or summarize material and ideas at Wikibooks}}, and that {{tq|translations made by LLMs are not allowed on Wikibooks}}. The fact that you did not disclose your usage of AI is part of the problem, but disclosing it does not make it allowable either.
::More broadly, based on what you've said above, the content of this book is a reflection of your personal theories on writing. This is essentially [[Wikibooks:Original research]] and is not permitted. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 22:36, 13 May 2026 (UTC)

== [[Suicide]] ==

I realize this book has been nominated for deletion before ([[Wikibooks:Requests for deletion/Suicide|1]], [[Wikibooks:Requests for deletion/Suicide (2)|2]], [[Wikibooks:Requests for deletion/Suicide/Suffocation|3]]), but it's been over ten years since the last nomination. The project's position on what material is in its educational scope has shifted, as have some of the facts on the ground.

* The chartered purpose of Wikibooks is to produce &quot;open-content textbooks&quot; (cf. [[Wikibooks:What is Wikibooks?]]) which are suitable for use in an instructional environment. Providing educational information about suicide in the context of psychiatry could certainly be in scope, as psychiatry is an educational topic; however, instructional material on how to commit suicide is not an educational topic, and should not be considered in scope.
* This book is, and has always been, primarily intended as an instructional work guiding users on how to commit suicide. It provides effectively no meaningful analytical content ''about'' suicide as a topic. Most of the original content in the book was imported from an early-2000s wiki associated with the &lt;code&gt;alt.suicide.holiday&lt;/code&gt; Usenet group, the &quot;ASH wiki&quot;, which was specifically and unequivocally dedicated to describing and recommending methods by which readers could commit suicide, and this has carried through to the current version of the book.
* Most of the content in the book was removed in 2020 (by redirecting it to the book's main page, e.g. [[Special:Diff/3660495]]) over concerns that it was created by a WMF-banned user ([[User:Leucosticte]]), and because it was likely in violation of the ASH wiki's (unclear) copyright. These changes removed most of the content of the book; much of what remains is image gallery pages like [[Suicide/Blades]] which have no educational value.

Suicide is a sensitive topic; if it is covered by a textbook, it should be covered tastefully and with an aim to educate. This book is largely the opposite of that. Having it here is doing more harm than good.

If this book is deleted, the following related pages should be deleted as well:
* [[Template:Suicide methods]]
* [[Template:Infobox suicide method]] (currently unused)
* [[User:Leucosticte/About ASH]] - from the ASH wiki, as mentioned above
* [[User:Leucosticte/Frequently Asked Questions]] - also from the ASH wiki
[[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 22:41, 21 July 2026 (UTC)
: {{keep|weak keep}} a)&amp;nbsp;Age is no argument. There are many stale underdeveloped books I would rather delete than keeping around. b)&amp;nbsp;The book’s topic is exceptionally difficult to write about. ''This'' impedes collaborative authoring. c)&amp;nbsp;The book does not really explain ''how'' to commit suicide (like a step‐by‐step guide), neither is it the book’s learning objective. d)&amp;nbsp;Even if ''you construed'' the chapter summarizing various suicide methods ''as instructions'', instructional material on how to commit suicide ''is'' an educational topic. In most ''present‐day societies'' it is not ''ethical'' to teach students how to commit suicide, though. e)&amp;nbsp;Therefore the correct path is to first alter the [[WB:WIW#Wikibooks includes instructional texts|project scope]] to censor books on ethical grounds ''and then'' nominate the book for censorship. ‑‑[[User:Kai Burghardt|Kai Burghardt]] ([[User talk:Kai Burghardt|discuss]] • [[Special:Contributions/Kai Burghardt|contribs]]) 04:50, 28 July 2026 (UTC)
::Re. c: most of the explicit directions were edited out in 2020, as noted in my nomination, but are still visible in page history. For a couple of explicit examples, see e.g. [[Special:Permalink/3318613]] or [[Special:Permalink/3654645]]. Providing specific instructions was the original intent of this book, and it has never escaped that legacy. If someone were interested in writing a book ''about'' the phenomenon of suicide, they would be better off starting afresh. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 05:26, 28 July 2026 (UTC)
*'''Delete all'''. ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 16:17, 28 July 2026 (UTC)
* '''Delete all''' per the nomination above. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 02:17, 30 July 2026 (UTC)
* '''Keep''' with caution. Rename to &quot;suicide prevention&quot;?--[[User:TunnelESON|TunnelESON]] ([[User talk:TunnelESON|discuss]] • [[Special:Contributions/TunnelESON|contribs]]) 04:03, 2 September 2026 (UTC)
*:Re. the rename: absolutely not. There is no content in the book about suicide prevention. If you are interested in writing a book on that topic, please start a new one. [[User:Omphalographer|Omphalographer]] ([[User talk:Omphalographer|discuss]] • [[Special:Contributions/Omphalographer|contribs]]) 18:48, 5 September 2026 (UTC)

:{{keep}} - 
:1. &quot;instructional material on how to commit suicide is not an educational topic&quot; - I think it can be construed as one depending on the person (and does not have to imply that the person is at risk)
:2. Not a reason.
:3. Not a reason. It is up to the community to decide whether to accept a banned user's work. [[User:Leaderboard|Leaderboard]] ([[User talk:Leaderboard|discuss]] • [[Special:Contributions/Leaderboard|contribs]]) 13:37, 6 September 2026 (UTC)

== [[Chess Opening Theory/1. g4/1...Na6]] ==
Nonsense position, one of the worst opening moves for White countered by a move hurting development for Black. [https://www.365chess.com/search_position.php Searching] on 365chess.com finds zero games with this position. See also a similar [[Wikibooks:Requests for deletion/Chess Opening Theory/1. e4/1...e5/2. Na3]]. [[User:1234qwer1234qwer4|𝟙𝟤𝟯𝟺𝐪𝑤𝒆𝓇𝟷𝟮𝟥𝟜𝓺𝔴𝕖𝖗𝟰]] ([[User talk:1234qwer1234qwer4|𝗍𝗮𝘭𝙠]]) 02:20, 13 September 2026 (UTC)</text>
      <sha1>oul17jw5p7mzhjt395h0z97cdu5cgk5</sha1>
    </revision>
  </page>
  <page>
    <title>JavaScript</title>
    <ns>0</ns>
    <id>10884</id>
    <revision>
      <id>4669830</id>
      <parentid>4529246</parentid>
      <timestamp>2026-09-13T06:36:37Z</timestamp>
      <contributor>
        <username>JackPotte</username>
        <id>99248</id>
      </contributor>
      <minor />
      <origin>4669830</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3069" sha1="cc6cdz2u33g6g7kme9m0w4spd3i41qj" xml:space="preserve">{{book title|{{BOOKNAME}}|Scripting for the web.}}

This book is a guide to JavaScript, a scripting language widely used in web pages and web applications such as email applications. JavaScript is not to be confused with [[Java]], which is quite a separate language for creating stand-alone applications.

''This book applies to version 1.6 and later of JavaScript. Multiple versions of JavaScript are covered in this book.''

== Welcome ==
{{book search}}
{{print version}}
{{PDF version}}

* [[/Introduction/]] ([[/Relation to other languages/]])
* [[/First program/|Hello World!]]
* [[/JavaScript within HTML/]]
* [[/Other Script Types/]]
* [[/Syntax examples/]]

== Core Language ==
* [[/Lexical structure/]]
** [[/Automatic semicolon insertion/|Automatic semicolon insertion (ASI)]]
** [[/Reserved words/]]
* [[/Variables and types/]]
** [[/Numbers/]]
** [[/Strings/]]
** [[/Dates/]]
** [[/Arrays/]]
** [[/Regular expressions/]]
* [[/Operators/]]
* [[/Control structures/|Program flow I: if, switch, try]]
* [[/Loops/|Program flow II: loops]]
* [[/Functions/]]
** [[/Anonymous functions/]]
* [[/Object-based programming/]]
** [[/Objects/]]
** [[/Constructors and prototypes/]]
** [[/Inheritance/]]
** [[/Access control/]]
* [[/Closures/]]
* [[/Debugging/]]
* [[/Optimization/]]
* [[/Strict Mode/]]
* [[/Shell/]]

== [[/Introduction to the Document Object Model (DOM)|Document Object Model]] and [[/DHTML|Dynamic Websites]] ==
* [[/Runtime document manipulation/]]
** [[/Finding elements/]]
** [[/Adding elements/]]
** [[/Changing elements/]]
** [[/Removing elements/]]
** [[/Changing element styles/]]
* [[/Event handling/]]
* [[/W3C event handlers/]]
* [[/Working with the mouse/]]
* [[/Forms/]]
* [[/Images/]]
* [[/Cookies/]]
* [[/LocalStorage/]]
* [[/Design Mode/]]
* [[/Bookmarklets/]]

== Client-Server Programming with AJAX ==
* [[/XMLHttpRequest/]]
* [[/Handling HTML/]]
* [[/Handling JSON/]]
* [[/Handling XML/]]
* [[/Working with files/]]

== Miscellaneous ==
* [[/JScript in Microsoft WSH/]]

== Appendices ==
* [[/Index/]]
* [[/Links/]]
* [[/Bookmarklets/]]
* [[/Useful software tools/]]
* [[/History of JavaScript/]]
* [[/Best practices/]]
* [[/Code structuring/]]
* [[/Generators/]]
* [[/Contributors/]]

== Related books ==
* [[ActionScript Programming]]
* [[Authoring Webpages]]
* [[Cascading Style Sheets]]
* [[:Category:CodeCook/Languages/JavaScript|Coding Cookbook: JavaScript]]
* [[HyperText Markup Language]]
* [[Programming Ajax]]
* [[Web Development]]

==Wikimedia==
* [[W:JavaScript|JavaScript on Wikipedia]]
* [[Wikiversity:Web Design/An Introduction to Programming with JavaScript]]

{{shelves|JavaScript scripting language}}
{{alphabetical|J}}
{{status|50%}}
__NOTOC__ __NOEDITSECTION__
[[de:Websiteentwicklung: JavaScript]]
[[es:Programación en JavaScript]]
[[fr:Programmation JavaScript]]
[[is:JavaScript]]
[[it:JavaScript]]
[[he:JavaScript]]
[[ja:JavaScript]]
[[ms:JavaScript‎‎]]
[[pl:JavaScript]]
[[pt:Javascript]]
[[ru:Книга JavaScript]]
[[ta:யாவாக்கிறிட்டு]]
[[vi:JavaScript]]
[[zh:JavaScript]]</text>
      <sha1>cc6cdz2u33g6g7kme9m0w4spd3i41qj</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/User/Docs</title>
    <ns>0</ns>
    <id>13106</id>
    <revision>
      <id>4669763</id>
      <parentid>4669652</parentid>
      <timestamp>2026-09-12T14:23:46Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669763</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="138182" sha1="34huewufuidc2ptvoztufx5bhwc9vsr" xml:space="preserve">{{ArosNav}}

==What is AROS==

Google translation 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=nl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Dutch], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Italian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=da&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Danish], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Polish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ja&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Japanese], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ko&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Korean], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Portuguese], 


*Computer Hardware
*AROS (operating system)
*Applications and Games
*User


[http://www.osnews.com/story/15819 AROS] is one of the intermediate levels between the computer hardware and the user. It is an open-source, clean-room implementation of AmigaOS 3.x that can be run on many different computer architectures. It runs primarily on PC x86 32bit and 64bit but also on amiga motorola 68k and compatibles, some ARM like the Pi and Apple Silicon, RISC-V and some old PowerPC. 

This page will cover enough to be able to write the downloaded image to your preferred media, to run a LiveUSB, LiveCD or LiveDVD on your office/home PC (Live meaning you can test without changing your existing setup) and, ultimately, to use it.  

Intel / AMD PC hardware support mostly covers the years 2000 to 2024. At the moment, AROS is '''not''' recommended to be '''installed''' on a working vital data holding machine. Instead, writing to and booting from a '''USB stick''' could be a much better option. 

AROS is an hobby OS and can co-exist with Windows(TM), MacOSX(TM), Android(TM) or Linux(TM) and act as an alternative. 
Unfortunately, Aros has few developers so upgrades and improvements can take [https://sourceforge.net/p/aros/mailman/aros-cvs/ time to appear]. 

AROS core is now [http://en.wikibooks.org/wiki/Aros/Developer/IncompleteAPIs ~80%] finished and is usable, so keep in mind that the software is still considered ALPHA/BETA and in constant development. Currently AROS is fun to play with on a curiosity level, but it is also interesting to program. AROS has some multimedia features and has internet access.  

Most importantly, use AROS to its maximum potential as it stands now, find ways to have fun with it and share your experiences. 


Good Sites to visit 

: [https://www.arosworld.org/home.php Aros World User forum] 
: [https://arosnews.github.io/ AROS News]
: [https://www.facebook.com/ArosWorkshop/ Aros Workshop], 
: [https://www.osnews.com/topic/amiga-aros/ OSNews] 
: [https://www.reddit.com/r/aros/ Reddit]


: [https://archives.arosworld.org Aros Archives] 
: [https://aminet.net/ Aminet]
: [http://www.amiga-news.de/en/ English translation of German site]


: [https://aros.sourceforge.io AROS] with [https://aros.sourceforge.io/download.html ABIv1 downloads] 
: [https://github.com/aros-development-team/AROS Aros ABIv1 Codebase]
: [https://github.com/aros-development-team/AROS/issues register ABIv1 issues] and [https://sourceforge.net/p/aros/bugs/ old defunct bugs notification site] 


: [https://sites.google.com/view/arosone Aros One x86, x64] 
: [https://tinyarosdistro.flazio.com/ Tiny Aros x86 and x64]
: [https://arosnews.github.io/aros-portable/ AROS portable USB3 stick images of hosted Aros One x86 and x64 on debian] 
: [http://vmwaros.blogspot.com Icaros Desktop x86 now on sabbatical, very old edition] 
: [https://sites.google.com/site/arosaspireone AspireOS, of the netbook Aspire One, very old edition] 
: [https://github.com/deadwood2 Deadwood's builds], [https://www.axrt.org/download/aros/v11/ v11 64bit PC builds], [https://axrt.org/downloads-aros Updated i386 32bit PC builds], 
: [https://github.com/ezrec Ezrec x86 m68k mirror of old svn version]


: [http://arosalive.blogspot.co.uk/p/10-basic-aros-how-tos-tutorials.html Basic How To guides] 
: [http://arosgamer.blogspot.co.uk/ AROS Playground], [http://thewetmachine.net/tag/aros/ Jess Wet Machine], [https://aroshacking.wordpress.com/ Jon Robertson's AROS Experiences and FPC Free Pascal], [], 
:[http://www.apollo-accelerators.com/ Apollo Accelerators m68k], [http://www.amigablogs.net/ Amiga Blogs], [http://blog.a-eon.biz/blog/ Trevor Dickinson blog], 


: [https://forum.amiga.org/ Amiga OS AOS 3.x forum] 
: [http://eab.abime.net/ EAB Amiga] 
: [http://www.amigaworld.net/ AmigaWorld] 
: [http://www.ppa.pl/ Polish Amiga Like News] 
: [http://www.apollo-core.com/ Apollo Forum] 
: [https://amigaalive.blogspot.com/ AmigaAlive]
: [https://www.amigalove.com/software Disk Mags]
: [https://amigachristmastree.ultimateamiga.com/ Xmas Amiga Game Jam]
: [https://www.reddit.com/r/amiga/ Amiga]


== Distributions aka Distros ==

For end users there are distributions (ready made with selected apps aiming to be easy to use), mostly created and maintained by one person in their own workflow/style. They reuse the nightly boot compiles to suit their needs and possibly other end users. You are free to create your own if required. 

* For native 64bit Intel/AMD: [https://sites.google.com/view/arosone Aros One x64], [https://tinyarosdistro.flazio.com/ Tiny Aros],
* For native 32bit Intel/AMD which will run on 64bit machines: [https://sites.google.com/view/arosone Aros One x86], [https://www.tinyaros.it/ Tiny Aros], 
* For native 68k [https://sites.google.com/view/arosone Aros One m68k], [http://www.aros-platform.de/ AROS Vision], 

'''Please, keep in mind that the distros listed above use a different ABI (abi v11) , which is NOT binary compatible with the official ABI V1.'''
* For hosted Linux usb drive image [https://arosnews.github.io/aros-portable/ x64 Debian hosted version of Aros One], 
* For hosted ARM there is [https://github.com/jonx/AROS-AArch64/releases alpha for Apple Silicon] and [https://aros.sourceforge.io/nightly1.html RaspberryPi 3 raspi-aarch64-system native 64bit] 


AROS was originally developed on Linux but can run on an Intel-based Linux distro as an app. As time has gone on, it can be run as an app on many more operating systems (Windows, FreeBSD, Linux and limited on MacOS). This may sound strange: an OS running on top of another OS. 
Basically, this is to take advantage of drivers (audio, internet, graphics, etc.) and compiler environments, in the existing OS, with which people may be already familiar. The term we use for what AROS does is &quot;Hosted&quot;. 

AROS Native is the term coined to describe AROS being run without any OS underneath it. It runs alone just like AmigaOS(TM) did. As this version does not benefit from &quot;Hosted&quot; drivers, dedicated ones have to be ported/written. Hence the smaller range of supported hardware / peripherals. We have other pages highlighting this support 


AROS is open source so basically everyone can take part. The source is public on github and there are new commits most days. AROS is automatically compiled daily, result are the nightly builds hosted on Sourceforge. The nightly builds are only used for testing changes, testing software and the starting point for distribution maintainers or even your own distribution. They are very basic, miss some functionality and apps like web browsers and generic general appearance which can be changed. 

* The [https://sourceforge.net/projects/aros/files/nightly2/ Nightly2], [http://aros.sourceforge.net/download.php nightly builds File Release Service] or [http://aros.sourceforge.net/downloads/ Sourceforge Project Web builds] are made automatically every night directly from the Github and in the past, SVN (Subversion) tree and contain the latest code for the AROS operating system. It should be noted that the builds have not been tested in any way and can be horrible broken. 

*ABIv11 offspring of 64bit PC ABIv1 i.e. another PC 64bit build 
*ABIv1 standard for most nightly builds, it is where the most work is done by developers 
*ABIv0 standard for PC 32bit intel / amd PC distributions for historic reasons 


==Media==

AROS media tends to boot in this tier list of media types, first internal HDD SSD, CD DVD drive, and finally usb drive (last two can depend on bios boot order) 

* USB .VHD 

[https://sites.google.com/view/arosone Aros One x86 and x64], with md5 below 

&lt;pre&gt;
0a656d53a9c902e9934000d8392e30ec *ArosOne-USB-1.3-64Bit.zip
7dd7119ab3e56d75ee852c137226b4d7 *ArosOne-USB-v1.2-x86_64-v11.zip
cf906eeaad4a83b3520b1896bdc6b0d3 *ArosOne-USB-v1.1-x86_64-v11.zip

e2eb8fe8cfd61c567b0152a61cf85251 *ArosOne-x86-v2.8-USB-IMG.zip
559909c75c2f56472c74267a7d075355 *ArosOne-x86-v2.7-USB-IMG.zip
93da5898508c1a8c05bb8991ab7bd117 *AROS One Image-USB-2.4.zip
59fcabd7090e47f12d54f7eb78cf0f45 *ArosOne-x86-v2.2-USB-Image.zip
24fb8de726ae8fc5fe5bac6d30f03dc5  ArosOne-x86-v2.0-USB-Image.zip
f3d725e990072edce633b59747911b6b  ArosOne-x86-v1.8-USB-IMG.zip
e089a24ae310e92fcc407a0125602ce8  Aros-One x86-IMG-USB-v1.6.zip
&lt;/pre&gt; 


[https://tinyaros.flazio.com/ Tiny AROS]

22bc993625b7c75b17263c0cc7e7baaa *Tiny Aros_copy.vhd (March 2024) 


There is usually a vhd image inside the zip that can be written to USB sticks which is so much faster than the old ISO written to physical CD DVD method. This .vhd can be written to an USB stick / ssd with these pieces of software below but it will erase the previous contents from the usb 

Windows - [https://www.raspberrypi.com/software/ RPi Raspberry Imager, use custom and see all files], [https://hddguru.com/software/HDD-Raw-Copy-Tool/ HDD-Raw-Copy-Tool], [https://rufus.ie/ Rufus up to version 3.20 may work with VirtualBox HD vhd images with Win7 but not some Rufus 4.x versions], [https://etcher.balena.io/ Balena Etcher but may spy on you], 

Linux   - [https://www.raspberrypi.com/software/ Raspberry Imager Ubuntu], Suse Image / Multi writer, dd, 

Mac     - 


* Virtual Machine .ISO or CDs DVDs 

 The native iso images are currently not compatible with Ventoy, Yumi, MultiBootUSB, Easy2Boot E2B, or similar 

&lt;pre&gt;
617a905b1665128c5e05f94dcc48e7f1 *AROS-One-v1.3-64Bit-v11.zip
11c8a147fcad7ecf52ae3a43e1934b69 *ArosOne-DVD-v1.2-x86_64-v11.zip
f93053d3b9ccf304d7e6ac3389e1987b *ArosOne-DVD-v1.1-x86_64-v11.zip

86d808a40dc7be389a758799a9b4f595 *ArosOne-x86-v2.0-ISO-DVD.zip
f1fc8599ef6a39e5df394e0f41d55526 *AROS-One-x86-ISO-DVD-v1.6.zip
&lt;/pre&gt;


You can use a virtual emulator like VirtualBox, VMWare to mount the iso image which can then be used to boot and/or install to USB. 

No current software can write an AROS ISO to a Pendrive. The author of ‘Rufus’ (who used an Amiga 500 as a child) once tried, but when he saw the system composition, he said he was unable to do it.

The solution is to boot the ISO from a VM (WMware, VBox), then install the AROS build on the Pendrive, which will eventually become a Live Pendrive that can be booted on a PC.

The only precaution is that in some cases it is necessary to thoroughly clean the Pendrive of any partitions and remove any bootloader that is not AROS. The Pendrive must remain raw without any partitions.

You can clean the USB stick on a PC with a program that manages hard disks. You need to do a partition wipe. On some USB sticks, you can clean it with InstallAROS.
For some USB pendrives, please use a reputable partition editor to remove any and all partitions from a usb pendrive as HDToolbox cannot do this task sometimes with a wipe all option. 


Previously the only installation option was CD-RW or DVD-RW, since the whole system can be burnt onto a single disk and can be reused when the next version is released. Good branded discs like Taiyo Yuden (later JVC) or Verbatim should be used to reduce frustration later. The days for this media is gone but kept here for information 

Since nobody currently sells AROS on any other media, you will need access to a CD/DVD burner to create the installation disk yourself. After it is on a CD or DVD, then access and writing to USB pendrives becomes available (this should be viewed as an outdated or last resort alternative method now), as well as using good USB manufacturers like Sandisk, Kingston, etc. rather than some other no-names. 

Try burning it to a CD-RW or DVD-RW using your CD/DVD burning program (most burning software have a burn iso option). The ideal writing speed is 2x or 4x, higher speeds can give errors and problems.  Check the writing integrity of your CD or DVD if your software has an option to do so before going any further. 

Standalone portable usb cd dvd drives do not boot physical burnt discs, please use an internal ide sata drive instead. 


* SD-card
For [https://aros.sourceforge.io/nightly1.html ARM Pi Aros 64bit], copy the files onto a FAT32 formatted micro SD card. 


==Booting==

The LiveUSB, and in the past LiveCD LiveDVD, is designed to trial (test drive) various operating systems without having to install them to your working system. 

Since 2011, UEFI was introduced to replace the original PC BIOS which made booting media more confusing. Some changes in the UEFI/bios may be needed 

*go into the bios using esc, f2 or f? and disable the Security -&gt; Secure Boot and maybe apply option for Legacy IDE mode 
*you may have to press F9, F10 or F12 or p on boot up to present a device boot options like USB or CD/DVD 
*disable the Fast Boot config so it would recognize portable DVD-drive and changed the Boot-sequence

Secure boot was introduced by Microsoft and later consortium, control what operating systems work with Secure Boot via shims. 
For Aros, it is best to disable and save the turn off change to Secure Boot (if you dual boot with Windows this will cause issues with further Window boots) 

 For the best experience, it is advised to install to another SSD than the one Windows resides on. 

The grub part of the boot should be fully automatic, and you should see a multiple choice graphic card screen after 10 seconds for USB or 40 seconds CDs and DVDs. 
If boot does not occur within a minute, please reboot and choose the VGA boot option as it relays a message stream so you can see where the issue lies. 

After the grub graphics choice, AROS takes over the booting and any issues can arise here 

If possible please use a branded usb pen drive as most of the time when we get reports of &quot;crashes right after grub boot selection&quot; it is mostly due to the recorded pendrive as they are made, notoriously on a will it work / will it fail nature, every time it is used. 
&lt;pre&gt;
So one usb drive written may stop at a System halted. Reset the machine. 
Or another pendrive will show give errors Smart Filesystem request - Volume 'Aros Live Drive' (DU0: usbscsi.device unit 0) There was an error while accessing this volume: 
Or if a FAT32 partition present - FAT filesystem - Device USBSCSI0P1 has a read error on block xxxxxxxx - 
&lt;/pre&gt;
Sadly, no drive even branded are resistant or totally reliable, so the only solution is to try another pendrive, and possibly to repeat, until no errors. 
It will give an indication on how reliable the usb drive could be. 


=====Advice for various machines=====

Some of the stages involved and shown on the display in a typical AROS boot start up 

&lt;pre&gt;
[MultiLoader]
[ELF Loader]
[Boot]

[HPET] 
[Kernel:ACPI]
[Kernel:APIC-IA32]
[Kernel:SMP APIC]
[HiddStorage]

ACPI: ????
ACPI Error 
[ACPI]AcpiOs????
[BattClock] Got RTC century offset 0x32 from ACPI 

[PCI] Scanning bus ? 
[AHCI] Sata 
[Vesa]  only if vesa is chosen as graphics option 

[ATA] detect hd &amp; cd drives 
[ATA0?] ata-identity 
[packet] fat.handler be.handler, etc. 
[DOS] 
[Storage:Bus]
[Storage:Controller]

[MSS] USB setup
[ehciInit] Port ? maps to controller ? 

[I2C] 
[ATI]
[drm] nouveau 
[AROSTCP]   if you have network driver prefs set up to start when booting 


&lt;/pre&gt;

; If boot fails, please give us some indication (pictures or videos) where the boot stops and the message(s) on screen. 


AROS's native SATA/AHCI driver doesn't always work. If you get errors related to ahci.device, try disabling it. At your chosen boot entry in the GRUB menu, Press E, scroll down to the ahci.device entry, and add a # or ; at the start of that line or delete it with Ctrl-K. Then press Ctrl-X or F10 to boot. 

If your disk isn't accessible at all with this change, you might need to change the SATA controller to IDE legacy mode in the BIOS: however, making this change will likely cause problems booting Windows on the same machine (if it's already installed). To disable ahci.device permanently, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and remove the ahci.device line from all boot entries you intend to use.

SATA AHCI Timeout while waiting for device to complete operations with BIOS SATA entry set to AHCI mode stops at &quot;waiting for bootable media&quot; screen, changing BIOS SATA setting back to IDE mode may allow it to continue booting 

The ATA driver doesn't always work. If you get errors related to ata.device, try using the alternative in sys:devs/alt which is an older version.  Press E when your chosen boot entry is highlighted in the GRUB menu, scroll down to the ata.device entry, and change it to read &quot;module /Devs/Alt/ata.device&quot;. Then press Ctrl-X to boot. To make this change permanent, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and change the path to ata.device in all boot entries you intend to use.


Further options (removing the &quot; &quot;) to add to the GRUB menus to disable certain other components for debugging:

&lt;pre&gt;
Disable AHCI                        &quot;AHCI=disable&quot;
Disable NVME                        &quot;NVME=disable&quot;

Disable ATA:                        &quot;ATA=disable&quot;
Disable ATA:                        &quot;ATA=nopci,nolegacy&quot;
ATA safe mode:                      &quot;ATA=nodma,32bit&quot;
Disable IDE from SATA:              &quot;ATA=32bit,nosata2pata&quot;
VIA / SIS with cdrom read io errors &quot;ATA=nodma,nopoll&quot; 

noacpi                   all [PCI] devices to be invisible to AROS. disk drives work but network, sound won't 
acpi=strict              if there are issues with sound after boot 

noioapic                 alternative to no acpi 

Set AHCI                            &quot;AHCI=force150/force300/force600&quot;
Disable AHCI/SATA:       comment out with a # ; or remove ahci.device line with Ctrl-K

Disable USB:             comment out # ; or remove pciusb.device and poseidon.library lines with Ctrl-K
Disable native graphics: &quot;nomonitors&quot;
USB3                     &quot;USB=xhci&quot; 
&lt;/pre&gt; 

Other useful grub command line options - nomonitors, noacpi, vesahack, nopoll 

Press Ctrl and X together (or F10) to exit and boot with the new options. Just experiment with different variations until successful. Those working options will need to be reused with every reboot of AROS until you can edit the grub.cfg and make it permanent i.e. install to hard disk or USB. 


* If you use VESA mode, you can see the debug log if you add 'vesahack' to the command  line.  This  will set up split-screen mode. In the upper half you'll see AROS screen, in the bottom - debug log. 
* ACPI ie. PCI hardware - If  you  get  crashes  at  early boot, try adding 'NOACPI' to the command line 


If you're having boot issues and have a null modem cable and a spare pc, a boot log is always useful. Edit your grub line to include debug=serial but would try with an with sysdebug=all in the line later as it can cause issues booting on machines with sysdebug=all enabled (corrupts the cpu initialization). 

However, if you feel you have found a genuine bug/fault in AROS that needs attention, please use the [http://sourceforge.net/tracker/?atid=439463&amp;group_id=43586&amp;func=browse bug submission form] to record as much information about what happened, why, and what hardware etc. you have so that people may try to assist you 


For Virtual machines VMWare VirtualBox, etc., attach and press play to start the ISO image 

If booting hasn't worked then it could be down to Bios/UEFI settings  


=====nvme.device=====

 Since 2018, nvme drives are standard on most machines 

The requirement is that a PC can boot with legacy mode/BIOS at the moment - Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

 This is still in testing and its' use should not be on or near precious own data 


=====AHCI=====

 Starting taking over since 2011 on a lot of machines 

* Check that UEFI (replacement for PC BIOS) has options set to remove UEFI SecureBoot option and apply CSM 
* SATA drive is set for Legacy or a mixture AHCI/IDE and not AHCI 


 AHCI sata can be very difficult to get working

Most Windows installs are already set to AHCI sata, changing this to a legacy IDE mode setting can help but please check if Windows will still boot. Some hardware like Lenovo laptops do not always like being set in legacy mode so only use as a last resort and aware of issues that can be caused. 

Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

With a 16C/32T chip machine, disable SMT and it should boot. 


=====ata.device for old BIOS's =====

 Pre 2010 this was the de facto standard method of providing settings to the computer at a lower level 

Some adjustments to the BIOS setup options are necessary (usually by pressing a key like DEL, F1, F2, F12 or ESC, p on the very early boot up of the computer). 

*Adjust booting options like moving USB hdd, CDROM higher as it is quite often disabled or placed lower by default, i.e. USB hdd, CD/DVD are placed at the top above the hard drive. Try looking here [http://www.windowsreinstall.com/articles/bios/ Windows] or [http://www.hiren.info/pages/bios-boot-cdrom Bios] or [http://www.wikihow.com/Set-Bios-to-Boot-from-a-CD-ROM Boot] or web search &quot;BIOS BOOT CDROM&quot;

* At the '''SAME''' time, check if the SATA/AHCI option is set to Emulate or IDE Legacy, though this can have '''issues''' with any OS already on the hard disk. If in doubt, do nothing and seek advice. 

* check that under BIOS settings you '''DO NOT''' have plug&amp;play OS selected as Aros at this point is unable to route interrupts on its own and needs the BIOS to do that. 

'''Save''' options changed at the end. 

PCITool can show if the motherboard chipset is in IDE mode. 
Class = 0x01 means STORAGE, Subclass = 0x01 means IDE. Also ProductID 0x3a20 resolves to non-AHCI mode in Intel ICH10 documentation.


==Installing==

We have a separate section [https://en.wikibooks.org/wiki/Aros/Platforms/x86_installing here]

We have a specific section for each CPU platform under the Specific platforms in the NavBar navigation bar on the right hand side menu 

error code (-6) when using the ahci.device (has writing to disk problem but not reading) is enabled. change this line in your grub and reboot 

&lt;pre&gt;
#module /Devs/ahci.device      &lt;&lt; disable
module /Devs/Alt/ata.device    &lt;&lt; add this line instead
&lt;/pre&gt;


==File structure overview==

AROS' directory structure is mostly identical to AmigaOS directory structure, with some additions.

AROS: or SYS: also known as DH0: (i.e. the drive partition with AROS system) has the following simplified list of the main drawers (Amigas term for directories/folders). 


{| class=&quot;wikitable&quot;
|boot:
| grub bootloader 
|----
|C:
| small apps, where AROS looks first for applications/games but will look at Tools, System afterwards
|----
|Classes:
| .class 
|----
|Devs:
| .device .resource and in their own drawers (folders) .audio, .hidd, network, graphics 
|----
|L:
| where .handler files go 
|----
|Libs:
| where .library files go 
|----
|Prefs:
| applications that adjust or setup AROS functions and capabilities 
|----
|S:
| startup scripts (for the aros boot process '''not''' grub) are stored here
|----
|Storage:
| place to keep old or alternative device drivers
|----
|System:
| applications associated with AROS operating system
|----
|Tools:
| extra applications
|----
|Utilities:
| extra applications
|----
|WBStartup:
| copy applications here to autostart with needed icons, drawers, data etc
|----
|}

See [[Aros/User/DOS#Drives.2C_Files.2C_Assigns.2C_Directories|DOS manual: Drives, Files, Assigns, Directories]]


=== Filesystem ===

Whilst the kernel is the heart, the filesystem is the blood of the system they are split into two categories (only a few are supported) 
&lt;pre&gt;
Journalling     - SFS PFS3 but also NTFS ZFS XFS ext4 
Non-journaling  - FFS FAT32(VFAT) but also exFAT BtrFS ext2  
&lt;/pre&gt;

Filesystem options for AROS to install 
* SFS default 
* Professional File System PFS3 [http://eab.abime.net/showthread.php?t=52234&amp;highlight=pfs3+free&amp;page=13 only on motorola 68k at the moment] 
* FFS very old now but left in for legacy usage 

Other [https://archives.arosworld.org/index.php?function=browse&amp;cat=driver/filesystem filesystems] for storage purposes 
* FAT32 favorite as most OSs support 
* NTFS (can lock AROS) 
* exFAT 

The only filesystems that really NEED defragging (i.e. disk tidy up) are from Microsoft(TM) - exFAT/VFAT/NTFS
*SFS tries to do exactly the same thing, but in certain cases it doesn't do as well as PFS. But you can defrag SFS 
*PFS *minimises* the amount of fragmentation, but does not automatically defrags as it saves files to the drive 

The setup of the below filesystems is usually done by the distro maintainer but if not....
&lt;pre&gt;
Copy L/exfat-handler L:

DOSDriver or Mountlist entry for an exFAT partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = exfat-handler
DosType        = 0x46415458
&lt;/pre&gt;

&lt;pre&gt;
Copy L/ntfs3g-handler L:

DOSDriver or Mountlist entry for an NTFS partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = ntfs3g-handler
DosType        = 0x4e544653

Also to make a read-only mount you can set:

Control        = ro
&lt;/pre&gt;


The Smart File System (SFS) is a journaling filesystem used on Amiga computers and AmigaOS-derived operating systems. It is designed for performance, scalability and integrity, offering improvements over standard Amiga filesystems as well as some special or unique features.  

SFS is written in C and was originally created and released as freeware in 1998 by John Hendrikx. After the original author left the Amiga scene in 2000, the source code to SFS was released and its development continued by Ralph Schmidt in MorphOS. 

Its development has now forked; as well as the original Amiga version, there are now versions for MorphOS, AROS, AmigaOS 3, and a version for AmigaOS 4, which have different feature sets but remain compatible to each other.  Versions for AROS, AmigaOS and MorphOS are based on different branches.  

In addition, there is a driver for Linux to read Amiga SFS volumes, GRUB natively supports it and there are free drivers to use it from UEFI.  The Linux version is [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ independent code].  

SFS (Smart File System) partially defragments itself while the filesystem is in use. The defragmentation process is almost completely stateless 

AROS SFS version has a 120GB partition size limit on hard disks and DVDs current 4gig size limit. 
The sources for the MorphOS 64-bit version of SFS were available but no porting to AROS has happened so far due to endian issues, etc. 

SFS Tools 
* GUI - arSFSDoctor, 
* CLI - sfscheck , [http://www.portacall.org/ sfsundelete], sfsformat, setcache hits a usability ceiling around the 10GB / 100,000 file mark, 

 sfscheck dh0: seek purge fraglist defragment

If there are two simultaneous file writes in progress and you reboot machine (or it locks up or crashes) you may end up with a corrupted filesystem. Although arSFSDoctor may help, you might have to copy the files to another partition, format the partition with the errors on and copy the files back. 


PFS / SFS are way more advanced and much much faster than the FFS. FFS is supported for legacy reasons only. 
The Professional File System (PFS) is a filesystem originally developed commercially for the Amiga and now distributed on Aminet with a 4-clause BSD license. It is a compatible successor of AmiFileSafe (AFS), with an emphasis on added reliability and speed compared to standard Amiga filesystems.  It also features multi-user abilities like the older MuFS. 

PFS has so many advantages including the important things, speed, the ability to recover all deleted files even simply same name by typing the command &quot;. Deldir&quot; convenient if done in Directory Opus, virtually deleted files are copied normally as if they had never been deleted, other convenience is to not ever invalidate the filesystem, just put it on top of the startup-sequence command &quot;diskvalid&quot;, which automatically corrects any irregularities in the system startup; PFS also provides a device for floppy which makes them very fast and takes advantage of the full capacity of the floppy including the area dedicated to the bootloader.

The device is split into two main areas. At the beginning of the device is the metadata section, which consists of a root block, and a generic array of blocks that can be allocated to store metadata. The rest of the device is another contiguous generic array of blocks that can be allocated to store data. The metadata section usually uses a few percent of the device, depending on the size of the device.

The metadata is stored as a tree of single blocks in the metadata section. The entire directory structure is recorded in the metadata, so the data section purely contains data from files. The metadata describes the location of data in files with extents of blocks, which makes the metadata quite compact.   

When a metadata update occurs, the system looks at the block containing the metadata to be changed, and copies it to a newly allocated block from the metadata section, with the change made, then it recursively changes the metadata in the block that points to that block in the same way. This way, eventually the root block needs to be changed, which causes the atomic metadata update.   

The filesystem is reasonably good at keeping files unfragmented, although there is a defragmentation tool available which will work on an online filesystem ie whilst being used. 

It was the first filesystem to introduce the concept of the Recycle Bin natively at filesystem-level to the Amiga, holding the last few deleted files in a hidden directory on the disk root.  

PFS version 5.3 was developed in C and a small portion of assembly code by Michiel Pelt.  There are endian issues to be overcome and adapting the small amount of m68k to C before use on intel based machines, etc.  


Autoupdate of files in a directory is already implemented in Wanderer, but not all file systems handle dos.library/StartNotify() in its full extent. It seems to work correctly in Ram Disk (thanks to AmberRAM handler), and it also works on SFS formatted devices. Other file systems might not yet have it implemented correctly though. 

The PC equivalent of the Amiga's RDB is the master boot record (MBR).


===Installing Applications===

The typical means to install applications under AROS/AmigaOS involves simply copying/extracting the archive (.zip .lha .rar .tar.gz) file containing the applications files to your own desired location i.e. drawer/folder. Once extracted, launching it by double clicking on an icon (recommended) or using the shell (alternative). Generally, this is on a separate partition from your AROS system files, however in reality it can be any location - including RAM: if you don't want it staying around too long especially when you switch off. 

At some time in the future it may be desirable for AROS to have a package-manager like subsystem able to retrieve information online about packages available for AROS and whether they update anything you currently have installed, however at the moment no such ability exists.


===User Data files===

AmigaOS has no notion of a default location to store user data files, and presently neither does AROS - though it may be desirable at some time to provide a common start location.

Some people, have extra small FAT32 partition(s) using HDToolbox, and not Qparted, to store data especially if a reinstall is ever needed. And then setup the usual Sys: (DH0:) and Work: (DH1:) / Briefcase (DU1:) partitions. 


===User Environment configuration files===

AmigaOS/AROS stores persistent system configuration data in directory assigned to ENVARC:.  This, by default, points to SYS:Prefs/EnvArc.

During boot a copy is made to another assign, ENV:, which is for runtime usage.  Changes to the files here will not survive a reboot.

Setting the env variables is generally done by applications themselves, or when necessary by the user using the SetEnv command. SetEnv has a SAVE switch to force the persistent copy in ENVARC: to be written also for when you are sure the change should be permanent.

Under the standard installation of AmigaOS style OSs, ENVARC: is copied to ENV: upon startup, which, if you have a hard drive installation, is in RAM:, hence, ENV: ends up being RAM:Env.

ENVARC: is the Environment Archive, which is the permanent copy of ENV:, which is the Environment.  It's roughly like the Registry in Windoze. 

Most programs do (and all should) store their settings in ENVARC: somewhere, and load them from ENV:.  The effect of this can be seen in the Preference editors.  If you Save your preferences, they go in ENVARC: and ENV:.  If you click Use, they only go in ENV:.  If you reboot, normally, anything saved to ENV: is lost, and is replaced with a copy of what is in ENVARC:.

you can set the default public screen for any tool started from a cli with the PUBSCREEN variable. So open the pubscreen, set PUBSCREEN to the name and start newcli for example, then the new cli window (and all following windows opened from that window) will appear on that public screen.


===Drivers===

For certain hardware, e.g audio, networking and , there is no auto setup. Just like the original Amiga OS. 
For audio, use AHI in the Prefs folder to set Music and at least Unit 0 with the appropriate driver and press Save. For ethernet and wifi, please use SYS:Prefs/Network 

All hardware support is placed in the Devs drawer (folder/directory). The network drivers &lt;something.device&gt; go in the Networks sub-drawer. Audio drivers &lt;something.audio&gt; are put in the AHI sub-drawer. Graphics drivers &lt;something.hidd&gt; are put in the Drivers sub-drawer. 


==Configuring==

AROS has mainly decided on a MUI-like requester&amp;menu clone called Zune so changing the background, icons, font, menus can be done with SYS:Prefs/Zune 

AROS has several desktop GUI front ends like 
* DOpus5 Magellan II, Wanderer and Scalos (medium) 
* AROS Workbench, Workbook (smaller) 

File / Directory managers like Dopus4, MCAmiga, 

App Launch Shortcuts like FKey, BoingIconBar, right mouse click on magellan, wanderer desktop, Amistart, etc. 

General usability decisions - Prefs/IControl, Prefs/Locale, Prefs/Input, Prefs/Fonts, 


Select an icon with left mouse button and then right click the mouse button and selecting Icon -&gt; Information gains access to the tooltypes tab where information can be edited 

CLI in icon's tooltypes means 'run it as if it was run from shell'
If, on the other hand, the WB parameter (or no parameter) is present in Tooltypes, Wanderer will execute the binary and, if provided, the options included in Tooltypes. 

WBxCLI is very useful for adding options to DOS Commands.

Important: AROS has a different way of managing icons. If you have an executable file, you will never be able to add a project icon. AROS will automatically recognise that it is an executable file and will transform the icon into a tool icon.


Icons are typically now .png pictures renamed as .info e.g. so Office application name would have a Office.png renamed as Office.info or MyApp.png as MyApp.info, etc.  

Leave Out menu option to leave app icon on desktop 

To select multiple icons and save their positions, click on the first icon and after while you hold the Shift key down select further icons and don't release it before SnapShot is finished.  You can also select a whole group of icons by pressing the LMB at the top left of the icons and while keeping the LMB down moving the power towards the bottom right. A expanding bounding box will appear and all the icons within it will be selected.  

Clean Up menu option (right mouse button -&gt; Icons) rearranges icons in a drawer or disk window into a neater condition. To use, open the window to rearrange and select Clean Up. To keep the icons in the new positions, select all the icons (shift key or mouse selection) and select 'Snapshot' and then Window and then again with All.  

In DOpus5, Scalos, wanderer, most files have an icon file associated with it. To change the default tool, select Icon menu, Information, and change the default tool string. For example, you could use Multiview, Editor and so on for most text, graphics and some sound files as long as the appropriate Datatype classes are installed. For scripts, set the tool to C:IconX 


We have new Icon edit tools in progress but if you need to...
 C:Join Image1.png Image2.png TO MyFile.info
is enough to make a dual state icon from two png images. You can then use Wanderer's menu Icon/Information on it to edit its fields and tooltypes.

[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/icon AISS toolbar images] unpack unarc them into RAM: and copy Images directory to SYS:Prefs/Presets/  AISS icons are looked for in PROGDIR:, PROGDIR:Images, SYS:Prefs/Presets/Images and then in TBImages: according to Open Amiga guidelines.  

there is Demos/iconscale which could be launched from S:User-Startup with two arguments, telling it the horizontal and vertical size. IE something like 
 Demos/iconscale 40 40
It will shrink icons... not sure if it will be very nice though. it doesn't work for the icons on the main desktop. 

there is an option to scale an icon to a bounding box afair, try iconsize followed by two numbers, like:
 iconsize 32 32

Is there any way in AROS to change an icon type from Project to Tool or vice versa?
Either the SIT option of [ ProcessIcon], or the TYPE option of HandleInfo (not sure if this one works at all, please test with care).
 processicon sys:pathoftheicon SIT=Project 

SIT Set type of ICON. Allowed types are: &quot;Disk&quot;, &quot;Drawer&quot;, &quot;Tool&quot;,  &quot;Project&quot;, &quot;Garbage&quot;, &quot;Device&quot;, &quot;Kick&quot; and &quot;AppIcon&quot;.

Btw, are your icons, the #?.info files, writable, is the W flag set ?


'''Decoration''' is Aros' way to provides a way to hide the old Workbench 3.1 style of windows and screens. In Prefs/Appearance some decorative theming elements need work 

Themes - SYS:Prefs -&gt; Appearance 
The default content of Prefs/Env-Archive/SYS/themes.var should be &quot;themes:ice&quot; but can be changed via the Appearance prefs, please do NOT click the Use button. Its useless. As you know, it will ask for the theme volume. Just pick the theme you want, click on Save, then reboot. 

* Decoration is on. Any time trying to change theme, you get: &quot;Please insert volume Theme: in any drive&quot;? 
You could check if you find SYS:System/Themes or if it is missing. Then you could open startup-sequence which you can find in drawer &quot;S&quot;. There should be a line: 
 Assign THEMES: SYS:SYSTEM/THEMES &gt;Nil: 
This does the trick. 
Open a shell and run: 
 Assign THEMES: SYS:SYSTEM/THEMES 
Than start the Theme prefs again... this should work 

* The theme is the only thing that could slow the system a bit, but it's not that performance impacting on most uses, and you can switch it off completely. Remove C:Decoration from the bottom of the file sys:s/startup-sequence. 

In each theme directory is 
*Env-Archive -&gt; Zune -&gt; global.prefs
*images -&gt; Gadgets -&gt; 20x20 pngs for Down etc 
*menu -AmigaKey - Background - Checkmark - SubMenu and config
*system - Arrowdown, Arrowleft, Arrowright, Arrowup, etc 


There is an [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/theme ALua/Zulu script] built for faster Wanderer skin management. You can modify config files, install new (wdz format/zipped skin files) and delete skins via the Theme Manager. This has not been updated in a long time and may not work. 


Exchange controls Commodities and can be opened with alt, ctrl, h 

Certain features are added if from Tools/Commodities like Blanker screensaver, ClickToFront and DepthMenu with .info icons are selected and dragged to /WBStartup folder 

Most apps can be autostarted by copying into SYS:WBStartup directory folder 
e.g. WeatherBar.zip can be downloaded, unzip and the contents of the zip copied to wbstartup folder 
 ClicktoFront and .info to SYS:WBStartup so always be activated when turning on the computer 

or add a text line to user-startup is SYS:S (scripts version of wbstartup) 

e.g. standard Amiga / AROS does not allow clicking of background windows to come to the front to make it easy to get to the window you need but it has the ability if these apps are copied again to WBStartUp or are added to SYS:S/user-startup script 

 run QUIET sys:Tools/Commodities/ClickToFront &gt;Nil: 
 run QUIET sys:Tools/Commodities/DepthMenu &gt;Nil: 
 run QUIET sys:Tools/Commodities/Blanker seconds=300 &gt;Nil: 

*AltKeyQ uses left Alt key to add strange letters 
*AutoPoint 
*Blanker screensaver 
*ClickToFront allows windows to be easily brought to the front 
*DepthMenu adds menu to select window easily 
*NoCapsKey
*Opaque 
*FKey - Although there are heaps of docks, menus and other launcher programs on the Amiga like OSs, FKey has got to be one of the quickest once learnt ways to launch programs, and it comes with the OS. In SYS:Tools/Commodities, the FKey commodity (Ctrl Alt F) allows you to make actions assigned to some combinations of keys 

&lt;pre&gt;
ALT TAB       Cycle Windows
              Cycle Screens
              Enlarge Window
              Shrink Window
              Toggle Window Size
              Insert Text
              Run Program
              Run Arexx Script
&lt;/pre&gt;

e.g.
&lt;pre&gt;
LAmiga F1               = Avail Flush
LAmiga F2               = Open Prefs
LAmiga F3               = Finder
Alt Tab                 = Cycle Windows
LAmiga Tab or M         = Cycle Screens
Alt Up arrow            = Enlarge Window 
Alt Down arrow          = Shrink Window
Alt Home                = Toggle Window Size 
                        = Insert Text             
LAmiga e                = Run Program             
                        = Run Arexx Script        
&lt;/pre&gt;

If your FKey GUI pops up when you start your Workbench up and you don't want it to, click once on the icon, go to the Icons-Information in the menu and make sure it has the tooltype set &quot;CX_POPUP=NO&quot;. 

Now let's launch it and assign the locale switching. After you double-click on FKey icon, launch the Exchange, choose the FKey from list and click the Show button. This will invoke the FKey window. You can see the ALT TAB in list assigned to window switching. Now enter the first key combination, say, ALT Z and go to the right panel. Choose Launch the program from pulldown menu and enter SYS:Prefs/Input as an argument. Append the USE switch and english preset name to the string as shown:

SYS:Prefs/Input USE SYS:Prefs/Presets/english

Click on the New Button to add the another combination. Now set the combination for your locale as shown above, replacing English name with your preset name. Click New button again and then Save Settings. Now you can use defined combinations to switch the layouts.


There is a system wide ARexx script capability (based on regina) that can manage many file manipulation task(s) but this would work only with those program that support [https://en.wikibooks.org/wiki/Aros/Developer/Docs/Rexx ARexx] like 

*Desktop - DOpus5, Scalos 
*Dock - FKey, 
*Files - Multiview, DOpus4, 
*Internet Apps - Odyssey, WookieChat, 
*General Apps - 


the shell can be modified with escape strings but not needed in most cases 


 Common Keyboard Shortcuts

&lt;pre&gt;
RAlt Right Alt Key 
LAlt Left Alt Key 
RWinKey Right Windows Key 
LWinKey Left Windows Key 
RAmiga Right Amiga Key (if one)
LAmiga Left Amiga Key (if one)
&lt;/pre&gt;

;Bootup Options 
:Spacebar during boot, enters the bootmenu which allows a boot without startup sequence, etc  

;Left Click 
:LAmiga = LWinKey = F11 

;Right Click 
:RAmiga = Help = F12 

;Mark 
:RAmiga and B 

;Cut 
:RAmiga and X 

;Copy 
:RAmiga and C 

;Paste 
:RAmiga and V 

;Search 
:RAmiga and S 

;Mouse Movement 
LAmiga and together with arrow keys - shift as well at the same time as well to move faster 

;Mouse Selection 
LAmiga and LAlt to select 

;Screen Switching 
LAmiga and M or N 

;HELP key 
Can sometimes be mapped to F11 but can be changed via FKey 


ComKeyRemapper or AmigaKeyremapper could swap RAmiga to another key press 


===DOpus 5 Directory Opus Magellan II===

Dopus 5.x is a whole desktop replacement on the Amiga Workbench (Desktop) 

DirectoryOpus app will assign DOpus5: to it's PROGDIR: automatically but if not add the below (edit SYS:System to suit where Dopus5 was installed) to your startup-sequence 

&lt;pre&gt;
Assign DOpus5: SYS:System/DOpus5 
DOpus5:DirectoryOpus 
;DOpus5:C/LoadDB
&lt;/pre&gt;

Left mouse button clicked twice on the desktop background brings up the Device List window. 
Green strip notifies SRCE (source) and if another is open it will be red for DEST (destination). clicking on the red strip changes to green 

Word list of actions with a left mouse click on the DOWN Arrow and directory stuff with &lt; button which mirrors the icons at the top of each lister 

single-key hotkeys? exactly the same as in dopus4, edit your functions (button bank, toolbar, menus etc.) and under the flags gadget is a key gadget, just click in it and press the key you want to use.

As for the extra text field... try turning off Extended lister key selection in environment / miscellaneous.

Shift and click on the icon - runs the icon 


DOpus5 Magellan 2 Directory folder drawer structure 
&lt;pre&gt;
ARexx       - Arexx scripts .rexx and .dopus5 to perform tasks 
Buttons     - 
Commands    - 
Desktop     - 
Environment - two environment files bundled:
 default gets loaded if you run DOpus as a normal app
 workbench gets loaded if you run DOpus as a WB Replacement (with LoadDB on startup)
Filetypes   - 
Groups      - 
Icons       - 
Images      - 
Modules     - compiled tasks 
Settings    - 
Sounds      - 
Themes      - 
WBStartup   - Use this if standard SYS:WBStartup gives cannot wait error messages 
&lt;/pre&gt;


Settings -&gt; Environment -&gt; Display -&gt; Workbench (Use) 


*Settings -&gt; Clock (add to title bar as well as the date) 

*Toolbar  -&gt; Editor (Right Win Key together with 1) for Copy, Move, Delete, etc above the Device List 
*Menu     -&gt;  (Right Win Key together with 2) 
*Buttons  -&gt; Editor (Right Win Key together with 3) 

*Settings         -&gt; Environment (Right Win key together with 4) for Backgrounds, etc 
*File Types       -&gt;  (Right Win key together with 5)
*User Menus       -&gt;  (Right Win key together with 6)
*Hotkeys          -&gt; Setup for quick shortcut keypresses (Right Win Key together with 7) 
*Scripts          -&gt;  (Right Win key together with 8)
*Icon Positioning -&gt;   (Right Win key together with 9)


Each Dopus5 theme are stored in a separate directory, named appropriately, which contains further sub directories 

* Font (amiga bitmap fonts)
* Screens (jpg or any picture supported by datatypes but not animations) 
* Sounds (wav but not iff 8svx ) 
* Icons (png newicons glowicons ) 
* Patterns (iff jpg png ) 


Just use wildcards in background filenames and you get a different picture every reboot 

For example, configure in Environment -&gt; Backgrounds -&gt; Desktop something like this:
&lt;pre&gt;
Work:Pictures/Backgrounds/#?
...or 
Work:Pictures/back#?.iff
...etc...
&lt;/pre&gt;


[https://aminet.net/util/dopus arcdir and themes]  


If you want to change the backdrop pic after a period of time, paste below into a text file called dopusrandbg.rexx and place in DOPus5:ARexx 

&lt;pre&gt;
/* Changes DOpus background image forever

   Start with:
   Run &gt;NIL: RX dopusrandbg.rexx 
*/

if ~show(&quot;L&quot;, &quot;rexxsupport.library&quot;) then do
	if ~addlib(&quot;rexxsupport.library&quot;, 0, -30,0) then exit 10
end

/* Configure these two lines for your needs: */
minutes=1
picpath=&quot;Work:Pics/#?.iff&quot;

address DOPUS.1

do forever
	call delay 3000*minutes
	dopus set background '&quot;'picpath'&quot;' desktop center custom
	dopus refresh background custom
end
&lt;/pre&gt;


If you don't want to use/open rexxsupport.library just for DELAY() then use the DOS Wait command

&lt;pre&gt;
/* random diropus backdrop changer */
/* by paul trauth, 1999 */
/* to do: non-repeatable randomness? */

options results

parse arg path

address DOPUS.1

/* get current backdrop pattern so it actually changes */

dopus query background desktop custom
currentpatt=result
lastslash=lastpos('/',currentpatt)
currentpatt=substr(currentpatt,lastslash+1,(pos('&quot;',currentpatt,2)-lastslash-1))

dir=showdir(path,'FILE','/')
num=0
do while dir~=''
    where=pos('/',dir)
    if where&gt;0 then do
        file=left(dir,where-1)
        dir=right(dir,length(dir)-where)
    end
    else do
        file=dir
        dir=''
    end

    if left(file,1) ~='.' &amp; file~=currentpatt then
        do
            pics.num=file
            num=num+1
        end
end

which=random(0,num-1,time(s))
newbg='&quot;'||path||'/'||pics.which||'&quot;'

dopus set background newbg desktop tile precision exact
dopus set background on
dopus refresh background
&lt;/pre&gt;


Clock format commands available are defined by locale. They are:
&lt;pre&gt;
 %a - abbreviated weekday name
 %A - weekday name
 %b - abbreviated month name
 %B - month name
 %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
 %d - day number with leading 0s
 %D - same as &quot;%m/%d/%y&quot;
 %e - day number with leading spaces
 %h - abbreviated month name
 %H - hour using 24-hour style with leading 0s
 %I - hour using 12-hour style with leading 0s
 %j - julian date
 %m - month number with leading 0s
 %M - the number of minutes with leading 0s
 %p - AM or PM strings
 %q - hour using 24-hour style
 %Q - hour using 12-hour style
 %r - same as &quot;%I:%M:%S %p&quot;
 %R - same as &quot;%H:%M&quot;
 %S - number of seconds with leadings 0s
 %T - same as &quot;%H:%M:%S&quot;
 %U - week number, taking Sunday as first day of week
 %w - weekday number
 %W - week number, taking Monday as first day of week
 %x - same as &quot;%m/%d/%y&quot;
 %X - same as &quot;%H:%M:%S&quot;
 %y - year using two digits with leading 0s
 %Y - year using four digits with leading 0s
&lt;/pre&gt;
like %a %d-%b-%y %H:%M or 


A WB ARexx interface, you could enter a cli command as a menu item to open a WB drawer like this...
 RX &quot;address WORKBENCH;WINDOW 'device:drawer' OPEN&quot;
Where device:drawer is replaced by the path of the drawer to open. 

The ARexx script would be capable to manage such a task but this would work only with those program that support ARexx 

&lt;pre&gt;
dopus addappicon
dopus addtrap
dopus back
dopus checkdesktop
dopus clear
dopus command
dopus desktoppopup
dopus error
dopus front
dopus getdesktop
dopus getfiletype
dopus getstring
dopus matchdesktop
dopus progress
dopus query background, font, palette, pens
dopus read
dopus refresh all, background, icons, lister
dopus remappicon
dopus remtrap
dopus request
dopus script
dopus screen
dopus send
dopus set background, font, palette, pens
dopus setappicon
dopus version
&lt;/pre&gt;

&lt;pre&gt;
lister add
lister addstem
lister copy
lister clear value
lister clearcaches
lister close
lister empty
lister findcache
lister getstring
lister iconify
lister new
lister query active all, dest source
lister query abort, busy, case, dirs, display, entries, entry, files, flags, handler, header, hide 
lister query label, lock, mode, namelength, numdirs, numentries, numfiles, numseldirs, numselfiles
lister query path, proc, position, seldirs, selentries, selfiles, separate, show, sort, 
lister query title, toolbar, value, visible, window
lister read
lister refresh
lister reload
lister remove
lister request
lister set busy, case, dest, display, field, flags, handler, header, hide, label, lock, mode
lister set namelength, newprogress, off, path, position, progress, separate, show, sort, source
lister set title, toolbar, value, variable
lister select
lister wait
&lt;/pre&gt;

The '''command''' allows you to call internal DOpus commands from an ARexx script

&lt;pre&gt;
command all
command wait copy
command read s:startup-sequence
command source 12345 makedir name noicon
&lt;/pre&gt;


*SFTP secure encrypted comms over internet using libssh2 and zlib (different protocol to the two below) on port 22 
*FTPS secured with https like security on port 21 
*FTP not secure and unencrypted protocol over internet on port 21 (should not be used today on the internet but for your own server) 


===Wanderer ===


Wanderer prefs in the prefs drawer - Appearance tab and Workbench icon allows backgrounds (wallpapers) icon text sizes, colors, etc but cannot use #? or *.* in the backgrounds file entry to randomly choose pictures - [https://developers.google.com/speed/webp/docs/riff_container webp riff container] issues with this format but Multiview has none. 

Enable the bar, you need to edit the text file ‘statusbar.prefs’. The change is simple: just change “False” to ‘True’.

Prefs/Env-Archive/SYS/Wanderer/statusbar.prefs 


===Scalos===

[https://web.archive.org/web/20180922220139/http://scalos.noname.fr/ Scalos] is not an OS replacement, it's a Workbench replacement. It replaces the desktop and graphical file management components. 

Scalos is 100% Workbench replacement with most functions working like the original Workbench ones. Undo and Redo available for most window and icon operations. Fully multitasking so every window has its own task. While loading icons, any window function (e.g. Drag&amp;Drop) is available. 

24bit color support with window patterns - Unlimited and easily configurable via tooltypes. Optimised backgroundpatterns routine so patterns can be tiled, centred or even scaled to fit into the windows. Live updating window scrolling - Supports middle mouse button panning and drawer (folder) windows can be iconified on the desktop. 

Icon imagetypes with all types are supported such as backfill or complement. Configurable surrounding iconborder. Icon support also visually highlights files which are soft-links in the file system. Icon dragging is more stable and far less flickery on graphics cards. Whilst dragging, icons are displayed with text and they can become transparent over anything where they can be dropped. 

Single-window lasso mode, with scrolling window contents invoked by dragging mouse with configurable qualifier key. Text icon lasso selection used to ignore &quot;Name column selects text icons&quot; flag. Support for backfilled thumbnail icons, with selectable color and transparency. Added option to always generate square thumbnail icons with preview icons for images - Thumbnails can be permanently saved in icons. 

Supports PNG icons with alpha channel and real transparency and displays OS3.5 GlowIcons and are all scalable. Iconborders with variations (normal, shadowed, outlined). 

Completely configurable, filetype-specific user-definable popup menus and tooltips. Plugin system to exchange or add features and can enhance the Workbench and make it more configurable. 

Filetype plugins to display filetype-specific information. - Currently, EXIF information viewer for JPEG images is included. Plugin included for 100% support of OS3.9 Workbench features. Plugin included for AREXX API compatible to OS3.9 Workbench. 

Online update with updater.module


Scalos works also as a Workbench replacement. In this case the 'emulation mode' has to be set by using Scalos' own version of LoadWB and offers 
* Scalos uses the Workbench Screen for its windows instead opening a new one 
* AppIcon, AppMenuItem, AppWindow functions are redirected to Scalos
* all Programs placed in &quot;WBStartup&quot; should start 
* The Screen will be reopened in case of changes in ScreenMode and Palette settings


&lt;pre&gt;
v1.0 (V39.201) - November 1999
v1.1 (V39.212) - December 1999
v1.2b (39.220) - June 6, 2000
v1.2d (39.222) - 2000 (latest public beta executable)
v1.3 (40.7) (beta) - August 2, 2001
v1.3 (40.22) - September 25, 2002
v1.4 (40.32) (beta) March 31, 2005
v1.6 (41.4) - March 27, 2007
v1.7 (41.5) - August 12, 2007
v1.8 (41.6) - March 12, 2009
v1.9 (41.7) (beta) - March 15, 2010
v1.9 (41.8) (RC1) - August 25, 2012 open source 
v1.9.2 (41.10) Deadwoods' AROS late 2022 32bit and 64bit build unifying the code base of ` for AROS x86 ABIv0, AROS x86_64 ABIv11 and AROS m68k  
&lt;/pre&gt;


Distros may have Scalos files under SYS:System/Scalos or Extras:Scalos. Known [https://github.com/deadwood2/AROS/issues/75 bug list], 


 Certain files like Menu13.prefs, Palette13.prefs, Pattern.prefs and scalos.prefs need to be in SYS:Prefs/Env-Archive/Scalos they can be found in Scalos:Storage/envarc and country drawer 

or run the &quot;Scalos Menu&quot; preferences program. Note if already setup with sub-menu entries and then re-save your menu prefs as it will now generate a new/overwrite prefs file called &quot;Menu13.prefs&quot; in &quot;envarc:scalos/&quot;. The same is also required for the new Palette prefs update, click 'Save' and a &quot;Palette13.prefs&quot; file will be saved in to &quot;envarc:scalos/&quot; directory. 


&lt;pre&gt;
ASSIGN Scalos:             SYS:xxx/xxx DEFER   
ASSIGN Libs:               Scalos:Libs add    
;ASSIGN SYS:Devs/Datatypes  Scalos:Devs/Datatypes   add  
Assign Theme:              Scalos:Themes/Default_Theme add 
Assign Locale:             Scalos:Locale add 

Protect Scalos:Tools/browse.script s add quiet 
Protect Scalos:Tools/OpenShell s add quiet 
Protect Scalos:Tools/run.script s add quiet 

run Scalos:Tools/LoadWB 
;Scalos:Scalos
&lt;/pre&gt;

Add the above to SYS:S/startup-sequence or SYS:S/user-startup '''before any Wanderer entries''' 


In the prefs drawer (folder) is the big prefs app Scalos_Prefs which covers these user setup areas 
&lt;pre&gt;
About Scalos
Paths               - should be preset 
Startup             - WBStartup drawer contents should auto run on each startup 
Desktop             - edit titlebar, icon layout and in misc, auto leave-out (drag icon to desktop) 
Icons               - 
Drag and Drop       - 
Windows             -
Text Windows        -   in misc, drawer sorting at start of listing if needed 
TrueType Fonts      - use Truetype fonts rather than system ones 
Miscellaneous       - 

Plugins             - after adding oop/title_clock.plugin %ti %da does not work, maybe needs ASCII .prefs added 
Modules             - ??
Menu                - setup for MainMenu and PopupsMenu with New Menu, RE Name, Key: shortcut, Command Properties 
FileTypes           - already added def_Project icons and def_Disk (hdd sdd cd dvd etc) support 
PopupMenu           - tweak how popups appear 
Pattern             - Wallpaper backgrounds with Type DE, each pattern in the list can be edited, Save as Pattern.pre 
Palette             - change the color of things , Save as Palette.pre 
&lt;/pre&gt;


Scalos_Prefs - Pattern - Minimum options to be changed are 
*DE Desktop/Background 
*SC Screen 
*TW Window/TextBackground ie Text listing showing if icon type not recognised 
*IW Window/Background ie Icons showing 

 Workflow - In &quot;Pattern List&quot; tab, select New - choose a picture, highlight in list, click in number box under New button and slide to another number, click on &quot;Defaults&quot; tab and adjust Pattern numbers slider to choose right picture for each of the above options - Click &quot;Pattern List&quot; tab to check eveything is OK and click Save 

Pattern List tab on Patterns Page - Allows you to compile a list of pictures (one at a time rather than a whole folder e.g. with #? or *.*), assigning a number Nr to one or more of them for easy reference. Using this number you will be able to assign the pictures to specific windows on the Defaults tab Page. If multiple pictures have the same number, one of the pictures will be chosen randomly. This will allow you to have random desktop pictures, random window backdrops etc. 

Defaults tab on Patterns Page - Here you can set the defaults for the background pictures for the Desktop, Screen, Window and/or Text Mode throughout Scalos. 
Randomize every time [check box] - Usually Pictures with the same number will be randomly selected as soon as the configuration loads. If this option is set, the picture will be selected as soon as a window with the same number assignment is opened. 

*Fit size: The picture will be resized to the dimension of the new window.You *MUST* have set GUIGfx on. asyncron layout: Pictures will be loaded and rendered while the windows opens (Like original Workbench). If this function is 'off', pictures will always be loaded before opening the windows. 
*Use friendbitmap : The picture is present twice in memory for best speed. This option has no effect if V43 picture.datatype or GUIGfx are used. Always relayout: If &quot;Fit size&quot; is set, the picture will be scaled everytime the window's dimensions change.
*Randomize everytime: Usually Pictures with the same number will be randomly selected as soon as the If more pictures have the same number, one of them will be chosen randomly. 

Patternlist New/Delete : Add a new picture. After that you should assign a number to it. The picture will be rendered as tiles. configuration loads. If this option is set, the picture

Asyncron-Task priority: You can set the CPU priority for the Task if &quot;asyncron layout&quot; is set. 
&lt;pre&gt;
Desktop: Number of the Picture for the main window.
Screen: Number of the picture for the Scalos-Screen.
Window: Number of the picture for the Scalos-windows.
TextMode: Number of the picture for the Scalos-windows in Text Mode.
&lt;/pre&gt;


Popup Menu preferences fully configurable menus (includes ToolsDaemon and ParM launch apps import), including support for context-sensitive Popup menus configs for top pull down menus for apps, etc. 

 Workflow - Scalos_Prefs then Menu, New Item, New Command add name at top then in Command Properties e.g. add Workbench and location e.g. DOpus:DOpus4 for apps  Command for c apps or Rexx for scripts or Plugin for  or AmigaDos for modules 

&lt;pre&gt;
DESCRIPTION	NAME/A      This is the title that is displayed in the top line of any popup menu  
INCLUDE NAME/A          Name of file to be included. Path can be relative to &quot;Scalos:FileTypes&quot; 

POPUPMENU      Starts the popup menu description section for this filetype.
&lt;/pre&gt;

The following Subcommands are allowed inside popup menus:
&lt;pre&gt;
SUBMENU &quot;NAME/A&quot;
ENDSUBMENU 


MENUENTRY &quot;NAME/A,KEY/K,DEFAULTACTION/S&quot;
ENDMENUENTRY 

INTERNALCMD	&quot;NAME/A&quot;
WBCMD &quot;NAME/A,STACK/K/N,WBARGS/S,PRI=PRIORITY/K/N&quot;
AREXXCMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;
CLICMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;

ICONWINDOWCMD &quot;NAME/A&quot;

PLUGINCMD
MENUSEPARATOR

ENDPOPUPMENU

TOOLTIP 
ENDTOOLTIP
&lt;/pre&gt;

&lt;pre&gt;
Starts the tooltip description section for this filetype. The following Subcommands are allowed inside popup menus:

GROUP &quot;ORIENTATION/K&quot;
ENDGROUP  
MEMBER &quot;HIDE/K&quot;
ENDMEMBER  

HBAR 
STRING &quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;
SPACE &quot;SIZE/N/A&quot;

DTIMAGE &quot;FILENAME/A&quot;
&lt;/pre&gt;


Each theme drawer (folder) has these further folders 
&lt;pre&gt;
About            - 
Desktop          - 
FileTrans        - 
FileType         - 
Icons            - 
Menu             - 
Modules          - 
PointerIcons     - 
Prefs            - 
Sound            - 
Window           - 
&lt;/pre&gt;


*Plugins
&lt;pre&gt;
devicefilter.plugin       
persist.plugin            should a crash or reboot occur - next time Scalos started, all windows re-opened 
title_clock.plugin        add digital clock to title see more below 
title_envvar.plugin       %ev, which can be used to display the value (a string) of the variable in the titlebar 
title_freepens.plugin     
volumegauge.plugin        
wb39.plugin               
wbrexx.plugin             plugin adds a Workbench 3.5+ compatible AREXX interface to Scalos internals 
xtwindows.plugin          left or right ALT or left or right SHIFT keys when open/close windows 
filetype.plugin           then run FileTypes-prefs and customize the filetypes (eg import from a DefIcons-brainfile) 
menu.plugin               
&lt;/pre&gt;


*Modules - delete, empty_trashcan, execute, find, format_disk, information, iconproperties, newdrawer, reboot, rename, systeminfo, windowproperties 


*Tools - scripts like LoadWB, quit.rexx, open_volume.rexx, 


In Scalos_Prefs-&gt;Filetype-&gt;Recognition  you can define the filetypes and on &quot;Action&quot; you define specific context menu for all filetypes defined in recognition (similar to magellan)
there is the same you must show all first (list is only limited) so you created a file type AAABBB, you need to have def_AAABBB icon 

Associating files with &quot;Scalos_FileTypes&quot; is very simple, practically it is very similar to Dopus4, first you create the Def_icons to assign to the file type (will be seen automatically ), then run &quot;Scalos_FileTypes&quot; you add the extension, fill in the descriptor (MATCH or PATTERN etc..) and save 

then you create a appropriate entry in the list and rename it, if def icon exists it is shown. Below you can define how files are identified. I use &quot;pattern&quot;, similar to magellan to identify file by ending. Then you click on the shown icon and define in it what program is used when you double-klick on it and save it. On the tab action you can define popup menu for it. 

defined all archive types from XAD in &quot;filetypes&quot;. If you change to &quot;action&quot; and click on &quot;archive&quot; you can define the context menu that is shown if you do not define a specific context menu for a filetype


Reset to Default in Scalos_Prefs resets all settings so BEWARE 


&lt;pre&gt;
The Scalos desktop screen titlebar may be configured using the main Scalos Preference program. This oop/time_clock plugin adds some additional placeholders:

    %ti, displays the current time in the default Locale format. e.g. &quot;10:43:37&quot;
    %da, displays the date in the default Locale format. e.g. &quot;Saturday 14 July 2001&quot;

Using the supplied prefs program for the plugin, or editing the ASCII file ENVARC:Scalos/title_clock.prefs you can use the following standard Amiga Locale values to change the formatting 

    %a - abbreviated weekday name
    %A - weekday name
    %b - abbreviated month name
    %B - month name
    %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
    %C - same as &quot;%a %b %e %T %Z %Y&quot;
    %d - day number with leading 0s
    %D - same as &quot;%m/%d/%y&quot;
    %e - day number with leading spaces
    %h - abbreviated month name
    %H - hour using 24-hour style with leading 0s
    %I - hour using 12-hour style with leading 0s
    %j - julian date
    %m - month number with leading 0s
    %M - the number of minutes with leading 0s
    %n - insert a linefeed
    %p - AM or PM strings
    %q - hour using 24-hour style
    %Q - hour using 12-hour style
    %r - same as &quot;%I:%M:%S %p&quot;
    %R - same as &quot;%H:%M&quot;
    %S - number of seconds with leadings 0s
    %t - insert a tab character
    %T - same as &quot;%H:%M:%S&quot;
    %U - week number, taking Sunday as first day of week
    %w - weekday number
    %W - week number, taking Monday as first day of week
    %x - same as &quot;%m/%d/%y&quot;
    %X - same as &quot;%H:%M:%S&quot;
    %y - year using two digits with leading 0s
    %Y - year using four digits with leading 0s

 like %d %m %y or %a %d %B %Y %p
&lt;/pre&gt;


Shutdown -&gt; right mouse button Scalos, About, Reboot, Shutdown 


ToolTypes can be added to the Scalos.info icon like 
*SCALOS_PATTERNNO=&lt;number&gt; : background image matching the number 
*SCALOS_NOTEXT : The Icon will be drawn without Text.
*SCALOS_NODRAG : The Icon will not be draggable. Its position will be fixed.
*Module iconproperties - Added SCALOS_BROWSERMODE tooltype support

runcommand parameters... in which case:
&lt;pre&gt;
%p = parameters
%w = directory path
%d = device-name
%% = literal percentage token
&lt;/pre&gt;


With the help of the wbrexx.plugin Scalos gains support for more of the compatible arexx API 

If an arexx command produces an error you will find the error code placed in the WORKBENCH.LASTERROR variable.

ACTIVATEWINDOW
&lt;pre&gt;
/* Activate the root window */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the &quot;Work:&quot; partition's window if already open*/
ACTIVATEWINDOW &quot;Work:&quot;
&lt;/pre&gt;

CHANGEWINDOW
&lt;pre&gt;
/* Change the root window; move it to position 10,30. * and change its size to 200100 pixels */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window */
CHANGEWINDOW active 20 40 200 100
&lt;/pre&gt;


Most of Scalos' issue are due to the flexibility of its' user configuring nature but if 


The sort menu plugin needs to be ported from ASM to C.

IIRC Scalos has a command line option to fully replace Workbench/Wanderer.

The Theme: assign is used by both Wanderer and Scalos but I didn't have any problems using both at the same time.


The Program will be started from the Shell.
If &quot;WB Args&quot; is set, with the Argument &quot;%p&quot; will be replaced by the path of the activated Icons. The Program will started with the specified Stack value.
IconWindow: Scalos opens the window of the specified path.


PlugIn: Starts a Scalos Menu-PlugIn.
If a Menu Item with empty name is specified, Scalos displays a separator line.
It's possible to Drag&amp;Drop an Icon in the Configuration Window. All values will be set accordingly. Entries may be dragged across the list.


Mac-like selection : This function activates a multiselection method used on MacOS or Win95. Don't have to hold down shift to drag them. Clicking on an already activated icon will
not deselect all other icons. 

MMB move: The window contents may be moved using the middle mouse button. 

WindowPopup title only: PopupMenu for windows can be opened only on window's title bars. 

FullBench: Screen-Titles removed and Main Window set Full Size. 
Scalos Prefs. Go to Settings-&gt;Scalos-&gt;Prefs and then the Misc section. Remove the tick against Full Bench. If you've enabled it, the titlebar will disappear when you select backdrop.


Default Icons saveable : The icons which Scalos generates if &quot;show all files&quot; is enabled, can now be saved
using &quot;snapshot&quot; menu option. load DefDisk first : Try to read the icons first from the DefIcons Path before using disk info. 


Hide hidden files : If this function is activated all files or directories where the &quot;hide&quot; flag is set will not be shown.

Many of my Icons display more than once on the screen, while on the workbench all seems ok.
The Workbench filters double displayed icons, Scalos does not. Solution: please edit the &quot;.backdrop&quot; file and clear double lines.

Background images not scaled. GUIGfx option not set or guigfx.library and/or render.library not installed.

If working with CD's causes crashs or Scalos doesn't work correctly.
Most Filesystems doesn't support the ExAll function correctly. Disable &quot;Use ExAll&quot; in Scalos prefs.

Scalos doesn't start any program in the WBStartup. WBStartup Path may be set wrongly or Scalos was not started in Emulation Mode (LoadWB etc) 
Some programs will not startup with error message &quot;has not returned, wait some more&quot;? and &quot;unable to open your tool&quot; 


need a def_icon with the same name predefined, then create an appropriate entry in the list and rename it, if def icon exists it is shown. Below this can define how files are identified. 
* either &quot;pattern&quot;, similar to magellan to identify file by ending
* or 
Then click on the shown icon and define in it what program is used when you double-click on it and save it. On the tab action you can define popup menu for it. All in all handling is of course different to magellan but can do similar 

For the RAM Icon, to obtain this you have only to copy the icon in the Icon Path as &quot;RAM.info&quot; or &quot;Ram Disk.info&quot;. All functions will automatically be performed 

sometimes cut into half or quarters when scrolled off screen or drawers moved - settings issue probably  

Sometimes leaves initial drawer window imprint on desktop when moved - settings issue 


Scalos AROS released a [https://github.com/deadwood2/contrib/tree/master/scalos new build V2022-07-21] with the following changes noted:
&lt;pre&gt;
Fixed:
    Numerous crashes when working on 64-bit with 64-bit heap
    Wrong background color of Scalos logo on Scalos splash window
    Backgroung image of Scalos splash window and Scalos About window is not visible
    Icon labels on desktop and in drawer windows are displayed using Topaz instead of Arial font
    Font.prefs are not being loaded on 64-bit
    Font.prefs are being wrongly saved on 64-bit
    scalos.prefs are not being loaded on x86 and x86_64, scalos is using always default preference
    scalos.prefs are being saved on x86 and x86_64 in format not compatible with m68k 
    NewPopupmenu.prefs is wrongly written
    Plugins are not loading at Scalos startup
    wbrexx.plugin is crashing at startup on 64-bit
    Multiple controls missing on Scalos Prefs/Icons page
    System crash when clicking on def icon image on FileTypes Prefs/Recognition page
    Status bar, control bar, buttons sometimes don't have images displayed
    Buttons in Scalos About window have white corners rendered where they should be transparent
    Crash when leaving out an icon
    Crash when adding a User-defined Button to Control bar without setting it's properties in Scalos Prefs
    Crash when removing any button from Control bar in Scalos Prefs
    Scalos Prefs allows editing TTEngine font properties when TTEngine is not present causing crash in Icons/Labels and Text Windows/Fonts pages
    deficons.prefs are not being loaded on x86 and x86_64
    Reset to default in FileType Prefs and Save does not save preferences

Won't fix:
    Scrollbars visible on titles of TrueType Fonts, PopupMenu, Menu, FileTypes, Pallette and Pattern pages of Scalos Preferences

Not fixed:
    Wrong rendering on DualPNG icons 
    Refreshing drawer windows is slow 
    Starting Prefs/Locale or Prefs/Input from Scalos causes other preferences to fail 
    Desktop wallpaper is damaged where Splay window was displayed 
    When started from Wanderer, after saving Scalos Prefs, reload does not re-open main Scalos window
    Difference in behavior between Cleanup from popup menu and Cleanup from top menu - possibly due to missing plugin, check Cleanup association in Menu Prefs
&lt;/pre&gt;


===DOpus 4 Directory Opus===

Copy DOpus4 app to WBStartup directory folder so it starts on boot up each time 

Another method is add the below to the bottom of the user-startup script in S: drawer/directory 
&lt;pre&gt;
run DOPUS:DirectoryOpus -i &gt;NIL
&lt;/pre&gt;
makes DOpus starts up in Iconified state at the top of Wanderer's screen. Left click on this to highlight and right mouse click to open. 


Just click on the sides of either outer edges of DOpus windows and it will display the parent device/volume list. 


DOpus saves it features in a CFG file which can be edited to suit anyones' needs by reading the [http://archives.aros-exec.org/index.php?function=browse&amp;cat=utility/filetool Dopus Manual] which is in Guide format. 


===BoingIconBar===

User chooses the apps to add to the dock at the centre bottom of the screen but has to be done manually, please use Save afterwards 

Or easier edit the text file of SYS:Prefs/Env-Archive/iconbar.prefs and save 

&lt;pre&gt;
SYS:System/Shell 
SYS:Tools/DOpus4/DOpus4
SYS:Utilities/Editor
SYS:System/SysMon
SYS:System/Scout
Work:Extras/Internet/OWB/OWB
Work:Extras/Graphics/Lunapaint
Work:Extras/Graphics/ZunePaint
AROS:Tools/MPlayer/MPlayer
Extras:Internet/AmiFox/AmiFox
&lt;/pre&gt;

right mouse click on bottom edge of screen where boingiconbar shows - select settings which opens BoingIconBar Preferences to add apps 

If no dock showing Add, to add apps click Add Program and search for the executable 

another method is to drag icons to ends of the bar and move them on the Bar using the Prefs/BoingIconBar 


===AmiStart===

On 32bit PCs only - auto generates the apps menu but scans the drive each time - AmiStart can choose apps you are not interested 

* how to disable annoying zune/mui 'bubbles'? 
try a right-click on AmiStart and release on Global settings. Then click on the bubbles gadget. Move the Show Bubbles slider all the way to the left.


===Fonts===

Install the #?.ttf files to SYS:Fonts/TrueType. Use SYS:System/FTManager to &quot;Install Font&quot; each #?.ttf file which will generate associated #?.otag and #?.font in SYS:Fonts. Use SYS:Prefs/Fonts to change system fonts and SYS:Prefs/Zune to change others. 

To achieve our goal we will use the Setup Locale, Input, Zune and Fonts, as well as The FTManager.

Begin

The first step you should do is to get the system to know that we speak and write in another language. What you need to do is to open the setup program and choose Locale country, and list &quot;preferred languages&quot; to put it first and then English. If you want the tab &quot;Time Zone&quot; and select city of residence to set the clock correctly. Of course we save our changes and continue opening the setup program Input. This sets the keyboard language as our beginning. When the language layout was created there was no option to switch to Aros keyboard (layout switching), so to write in the language you had to hold down Alt, something you encounter in other functions. This time working with the team of Aros to create a new keyboard layout to replace the old so we can get rid of the button Alt. For now though let only selected this layout and do not turn the switch on the keyboard.


Custom Keyboard Layout

[http://repo.or.cz/w/AROS.git/tree/HEAD:/workbench/devs/keymaps keymaps are in place but unfortunately when they are not, then indeed things become a bit 'low-level' as it involves redefining some tables with values that match your keyboards] 

only need to add your compiled table as new keymap. 

So taking a little peek here shows that it should be possible to compile using
 gcc -opc105_tr pc_105.c -nostdlib
where the pc105_gr/pc_105.c needs to be replaced with your own adjusted keymapname/c-file

[https://en.wikiversity.org/wiki/Enabling_Greek_Characters_on_Your_Keyboard General overview of Greek letters on keyboards] 


Installing fonts

*[http://aminet.net/package/util/wb/EPAGrWb System jaggy] 
*Outline resizable .font .otag 
In this step you need to download some fonts that can support the encoding in our system. The easiest way is to run the script &quot;Download Fonts&quot; you'll find in the folder OWB. This script downloads from the Internet, and unpacks some fonts for OWB web browser, which is placed under the folder Fonts:TrueType. But as these can only be used by OWB and not the system, which unfortunately does not see. To make them available to the rest of the system, open the program FTManager, you will find the folder AROS: System /. From there select the field &quot;Codepage&quot; option &quot;ISO-8859-7&quot; and list the font &quot;Arial&quot; and &quot;Regular&quot; form in which you must double-click with the mouse. In the window that appears, select the bottom right the checkbox &quot;Anti-aliasing&quot; button and then &quot;Install&quot;. Immediately folder Fonts: created files &quot;arialregular.font&quot; and &quot;arialregular.otag&quot;, which are necessary in order to see the system font. Do the same steps if you wish for other fonts.


Final stages 

After completing the above, open the folder AROS: Prefs / and run the program settings Fonts. In the new window, select the fields &quot;Icons&quot; and &quot;Screen&quot; as the font &quot;ArialRegular&quot; to the size you want. In the field &quot;System&quot; to give &quot;s_courier&quot;, which, however, because it is not True Type Font support Antialising, and may seem a little broken. You can also use the CourierNew, if you have installed the above procedure. After you save the changes and open the Zune program settings. In this set the &quot;ArialRegular&quot; font fields in tabs &quot;Windows&quot; and &quot;Groups&quot;, and save the changes. Reboot the system. To make sure that the above worked properly run NoWinED, which you will find under the folder AROS: Tools /. If that everything is working correctly you will see the menu and the settings window with Greek letters. You can also write in the language using the button Alt. Second program that you can try, which is fully localized, is WookieChat, which you will find in the folder AROS: Extras / Networking. And in this place all the menu and settings window works. 


===Windows===

*Intuition
The window you position and resize, you right click on that windows title bar and in the dropdown menu you snapshot from there.  Right click to show menu -&gt; Window -&gt; Snapshot Windows or All but it will NOT work if that folder has no icon (e.g. Disk.nfo) attached to it. You need a folder icon. The window information gets saved in it.  

As for maximising the window using a shortcut key - Alt and up arrow key 

The AROS-Shell windows can be moved, resized by editing sys:s/icaros-sequence 

&lt;pre&gt;
; run shell
if ${Icaros/autoshell} EQ true
  run QUIET c:newshell &gt;NIL:
EndIF
&lt;/pre&gt;

; slimmer right aros the screen 
run QUIET c:newshell con:0/150//300/ &gt;NIL:

; top right corner scr-x scr-y win-x win-y
run QUIET c:newshell con:600/150//300/ &gt;NIL:


*Zune - AROS version of MUI
Magic Menu type functionality is implemented in IControl preferences editor: in the frame called Menus, switch type from Pull-Down to Pop-Up and/or iControl just tick the sticky menu option. 


Windows outside screens causing a problem either uncheck &quot;Offscreen move&quot; for windows in IControl prefs editor. Or use FKey commodity and define two key shortcuts: 

* the first using the command &quot;cycle windows&quot; (for example ALT TAB); 
* the second using the command &quot;rescue window&quot; (for example ALT F5). 

Now you can cycle windows until the one you want to rescue, and then &quot;rescue&quot; it: it will move back inside your screen. 


How to save the window size on wanderer (snapshot all, snapshot windows)

Same for icon position on wanderer, can't save the position. Icon position cannot be saved yet, but you should be able to save the window position and size. sys:prefs - wanderer icon has option to save window size on exit but just for dh0. To get saving working on (DH1: Extras:) partitions try deleting the dh1 disk.info file, then reboot. The system should create a new dh1 icon. 


* how to set up permanently 'view all files'?
As for viewing all files, removing disk.info for that disk did the job 

* how to list and kill processes (xkill would be useful) ? 
sys:Extras/System/Scout can kill apps 

sys:Tools/Commodities/Exchange can remove available commodities


* how to restore 'go up' button in wanderer window? (it doesn't show up anymore).
If you're using Icaros, go to the theme prefs and make sure that decoration is checked. Also, some themes do not use a parent button, so try another theme. You may have to restart Aros before the theme will change.

* Is it really safe to turn off (hardware button) computer at any time (worried about USB hard disk)
yes you can turn off the computer IF none of the drives are in progress (i.e. writing). Best to use Wanderer menu option Quit otherwise 


===Say narrator===

SPEAK: is a write-only DOS device for text-to-speech abbreviated as tts. 
To check if available, type assign into the shell and at the bottom in the Devices: section should be SPEAK 

Examples of use 
&lt;pre&gt;
Copy S:Startup-Sequence SPEAK:
Echo &quot;Hello&quot; &gt;SPEAK:M/R/S150/P110
Echo &quot;DH1 EH0 L OW1&quot; &gt;SPEAK:A1
&lt;/pre&gt;

Classic options are M/F, R/N, S&lt;rate&gt;, P&lt;pitch&gt;, O0/O1, A0/A1, and D0/D1. O1 recognizes lines beginning with OPT/ as option changes. A1 treats input as narrator phonemes.

Long options select a speech engine:

Echo &quot;Hello&quot; &gt;SPEAK:ENGINE=narrator/VOICE=female/STYLE=natural/LANGUAGE=en-US

Supported selectors are ENGINE=, VOICE=, STYLE=, and LANGUAGE=. Values are case-sensitive backend identifiers. ENGINE=DEFAULT selects the system default. Narrator-compatible selectors continue through the classic translator/narrator pair. Other engines use speech.device. Direct phonemes require a narrator-compatible selection.


===Printing===

This needs further drivers written, we have postscript and write to file support only 


*Postscript

Best to set Printer Prefs in the Prefs drawer to print-to-file or parallel/USB port 


Save document in postscript or convert picture/text to postscript 

Print using compatible [http://en.wikibooks.org/wiki/Aros/Platforms/AROS_USB_support#printer.class_-_PostScript_3_and_internal_ghostscript_drivers Ghostscript printer] or Postscript printer 


*GutenPrint

Some work has been done 

;There are no individual drivers yet for HP's Photosmart, EPSON's EPL, CANON's, Lexmark, CUPS PPD, etc. 


*printer is simply not accepting IPP connections at the moment.

Please try the following steps:

Open the printer web interface in a browser:

 http://192.168.1.x/

Look for the network or protocol settings.

Enable IPP / Internet Printing Protocol.

Make sure TCP port 631 is open/enabled.

Save the settings and reboot the printer if the web interface asks for it.

 ipp://192.168.1.xx:631/ipp/print

 ipp://192.168.1.xxx:631/ipp/


===Files===

====File endings and datatypes====

* Check if the file has his own .info icon file with a tool set to open it. IIRC this has higher priority over the def_XYZ.info file association. 
* In ENVARC:SYS/def_Text.info or whatever def_ file needs changing, use Wanderer's menu Icon -&gt; Information and change the def_XYZ.info there. If you're on ABIv0 and want it to be applied immediately, you might have to copy it to ENV:SYS/ (or to reboot). 
* Identifying file types by file ending is only a fallback. Far better it is to search for magic words, for flac files this would be &quot;flaC&quot; according to this [http://flac.sourceforge.net/documentation_format_overview.html documentation]. 

For instance, to open PDFs with arospdf not localised in the default drawer of Icaros (Work:Extras/Applications/arospdf) but localised in a custom drawer in AROS. The default tools are defined in the icons in sys:prefs/env-archive/sys e.g. def_PDF. 


File type identification is done by datatype descriptors which you can find in Devs/Datatypes. The AROS build system has a tool which creates such datatype descriptors. 


'''Changing of default tools of existing icons is easy as shown above. Adding of new file types is not hard, but needs knowledge of the AROS build system.'''


The enduser way would be to download the attached file, which contained two executables:
1) createdtdesc, to make a new datatype description
2) examinedtdesc, to read/show existing datatype descriptions

use 2 to get an idea on how it things are currently done in aros by providing this executable a file from the drawer sys:devs/datatypes/ (alternatively you can find the original .dtd files here).

use 1 to make your new datatype. Use the accompanied FORMAT file (also here) to read how to make your own datatype descriptor. use 2 to get hints from other datatype descriptors.

Note:
When creating a new descriptor would advise against using the pattern property, but instead use the default pattern of #? and create a Mask that matches your filetype. This requires some research in order to discover how your filetype can be recognized properly. Of course with making something like a descriptor for an ascii textfile, you would fallback to using the pattern (e.g. #?.text as the filetype cannot be determined easily otherwise). 

&lt;pre &gt;
# name - choose wisely and informative. also used for icon's name.
# version - choose as you like as long as it complies with version rules
# basename - the 'root' datatype class. be aware that e.g. it can influence behaviour. for example when choosing binary and using tool multiview in project icon, the file will be viewed as binary file (choosing sound would tell mulitview to view the file as a soundfile). So this can influence the underlying tool being used. Could become messy if users started to modify the tool manually. 
# pattern - This is the file pattern match e.g. #?.text
# Mask - A mask to identify the file. Requires knowledge of the actual file structure. For example 'M' 'Z' for an msdos executable.
# GroupdID - not supported (AROS native) files - use syst as that would be the least intrusive in case an AROS tool/program tries to load such datatyped file.
# ID - In your case, the first four characters of the name at subchapter 1 (in lower case) (or less if name is shorter).
# flags - How the mask needs to be interpreted. In your case would be mostly DTF_BINARY in combination with (wanted or not) DTF_CASE (to tell if mask used letters are case sensitive or not)
# priority - the priority of how the type is handled so that on datatype could have precedence over another? In any case, document tells it to be mostly 0. 
&lt;/pre &gt; 

Now that you know each field and what it does (more or less), you write this fields in a text file for your own invented datatype, save it and create the actual dt with the tool in 1. in the end the created dt must reside in sys:devs/datatypes/ drawer.

Then you would create a default icon in sys:prefs/Env-archive/SYS drawer. Don't forget to reboot or copy .info file to ram:env/sys in order to test. also don't forget to set which tool to start f.e. c:lx or dh4:emulators/mycoolemulator

To test, open Wanderer then show all files and doubleclick on a file of type you just created. Alternatively you could use the 'open' command from shell (with file of datatype you just created as parameter).

And as a last note. it would perhaps be welcome to have a program like xicon and/or runprglist for AROS (unfortunately both without source, but something similar could be created for AROS).

Sounds complicated ?

Perhaps... but OS like windows needs a complete registry to be able to do things like this. And yes, i am aware windows has gui tools that does it (more or less) for you (by manipulating the registry). Same could be done for AROS (without integrating a registry in AROS that is ).

Would that suffice ?

red1+2: typos, reformatting.

disclaimer: please note that using these tools can screw up your currently installed support for datatypes when used incorrectly. Do not use if you do not understand what you are doing. Use at own risk.


==Network Connection==

AROS currently only has one real choice for TCP/IP networking - AROSTCP.  This is a port of the AmiTCP package from AmigaOS (TM), with a number of enhancements/fixes from AROS developers. 


 Please use Prefs/Network to set up wired, wireless or USB networking 
 Non USB wifi is easier, USB wifi can be an annoyance - remember to save whilst in prefs 


===Wired===

=====IPv6=====

Some support 


128bit IPv6 address packet 
&lt;pre&gt;
Local FD::/8
Global 2000::/3
64:ff9b::/96
&lt;/pre&gt;
NAT64 translates IPv6 to IPv4 
DNS64 


OS routing works with 
&lt;pre&gt;
MacOS Ventura 
Windows 11 with cloud account 
Ubuntu Jammy Jellyfish 
Android 10 (block google dns) 
&lt;/pre&gt;


====IPv4====

The top half of the IPv4 Configuration tab on the Network Prefs deals with the network card/USB and the lower half the router part. 

[[File:AROS Wanderer Network Prefs DHCP.png|thumb|DHCP Settings]]

'''Upper part of IPv4 tab''' 
* Click Add on the top right of the Prefs which opens a window called '''Interface''' 
* Enter Name as net0 (but can be anything as long as it is consistently used in other sections) 
* check mark on Active
* select device to be used using the '''right hand-side gadget''' of the box where the device name will go 
* set Unit to 0 
* IP Mode is default set to '''Get address from DHCP''' 


* IP Mode set to Manual if DHCP does not work automatically 

From the shell CLI,  ifconfig -a

Under net0: section, inet starting 192.168.x.xxx

* inet or '''Address''' of network card 
* netmask convert to decimal so 0x'''ffffff7f''' becomes 255.255.255.247 which is used to adjust the above '''Address''' into 
* broadcast 192.168.xxx.xxx

click OK


[[File:AROS Wanderer Network Prefs Manual.png|thumb|Manual Settings]]

'''Lower part of IPv4 tab''' 
* IP Mode Get address from DHCP (default) 


* or changing to Manual if automatic DHCP set up does not work 
* '''Gateway''' (Router Internal LAN-IP) (Default Route) = 192.168.0.1 (D-Link Netgear), 192.168.1.1 (Linksys 3com), 192.168.2.1 (SMC Microsoft), 192.168.1.254 (Belkin), 192.168.123.254 (USRobotics) else check with your router manual 
* first DNS = use 208.67.222.222 (opendns) or Gateway number above (to test web browser access to router) or 212.50.160.100 (google)  i.e. or whatever your ISP needs you to set 
* second DNS = use 208.67.220.220 (opendns) or Gateway number above (to test web browser access to router) or 213.249.130.100 (google) i.e. or whatever your ISP needs you to set 


* At the bottom of IPv4 tab, check mark the '''Start networking during system boot''' option 
* Save and reboot (sometimes Network restart fails, so reboot every time to be sure) 


'''an alternative way''' to AROS ifconfig -a, other OSs have similar for the same internet connection. Another connection will have different settings. 

e.g. From [http://www.ncsu.edu/resnet/windows/ipconfig/ Windows], '''ipconfig /all''' 
and note down the IP, subnet mask, default gateway, and DNS servers values and put these values in &quot;manually&quot; into AROS Network prefs. 

e.g. From Linux via dhcp router have a look at etc./dhcpc/dhcpcd-eth0.info 
* for manual input look at /etc/networks (IP or Gateway) and /etc/resolv.conf (DNS) 

 Please note that all in one routers (wired+wireless) or separate routers may need different settings 

IPv4 involves routing (192,168.x.x), firewall, NAT 


===Wireless===

[[File:MyArosWirelessSetup.png|thumb|Setting up]]

[[File:MyArosWirelessTCP.png|thumb|Shell commands to work out what is happening]]

We must first make certain you have a Atheros 5k chip inside acting as the wireless wifi option. Open PCITool in Tools directory. Down left hand side are a series of numbers 0.00.0 etc. Click on some at the bottom and hopefully one of them will say Atheros AR5??? or AR242?. 

or a Realtek RTL8187B, we can check using Prefs/Trident as this one is USB based 


There are many similarities with the above Wired set up so please read the above section as well 


* open Network/Prefs
* In '''IPv4 Configuration''' tab - click Add - enter net0 / active tick / #?.device / Unit 0 / IP Mode = manual (important if default DHCP does not work automatically) 

Make sure that any extra network names (e.g. eth1 or net1) should be deleted. If net0 already st previously, change net0 so that it shows associated with the appropriate device name like atheros5000.device or realtek8180.device. Having two entries here will cause sub-net problems. 

* Go to '''Wireless''' tab and click on &quot;Add&quot; button. 
* Insert network name (SSID your wireless network name use wirelessmanager to get it), select right &quot;encyption&quot; that is most likely &quot;WPA&quot;. 
* Key Type set as &quot;Passphrase&quot;. i.e. type in your password for your router (aka access key). 
* Unselect (no tick) &quot;hidden&quot; if it is selected, then apply. You may have to tick it if wireless does not work. 
* Finally, Save and '''reboot'''. 

For the best chance of success, set networking to start at boot, and then reboot with the USB adapter plugged in. 


===USB Ethernet===

Open SYS:Prefs/Network and in the IPv4 Configuration tag (top table covers your usb stick) 

* click Add button
* set Name as net0
* Tick Active box
* enter the usb-ethernet.device e.g. dm9601eth.device, usbpegasus.device or usbasixeth.device use SYS:c/devlist, '''Scout''' or trident prefs to get the correct spelling 
* set Unit to 0 (which is usual but check the messages from the bottom of the Trident prefs whilst plugging the device in to determine the unit number otherwise) 
* IP Mode is set to Get address from DHCP (make sure your router is set right for that) 
'''or manual'''
* IP Address of network card, i.e. 192.168.0.xx or 192.168.1.xx (xx being greater than 1) 
* Subnet netmask = 255.255.255.0 
* click OK

There can be sometimes be boot failures when using USB ethernet - plug the USB device in after boot and save the network prefs to make it work again. 


Lower part of IPv4 tab covers the router information 

* IP Mode Get address from DHCP 
'''or if manual settings'''
* Gateway (IP Address of router) = usually 192.168.0.1 or 192.168.1.1 but see router manual to make sure. 
* first DNS = use 8.8.8.8, 208.67.222.222 (opendns) or 212.50.160.100 
* second DNS = use 8.8.4.4, 208.67.220.220 (opendns) or 213.249.130.100 


===USB Tethering via Android smartphone===


Go to AROS Network Prefs (IPv4 configuration tab) and write type in &quot;usbrndis.device&quot; in the &quot;device&quot; textfield of &quot;Interface&quot; sub-window, which appears when you add a new device (or modify an existing one). Select &quot;Start Network during system boot&quot; and saved the configuration, the Connection is immediate no reboot is needed.&lt;br&gt;

usbrndis.device is a resident device (virtually always there) in fact, a driver is not present in DEVS:Networks &lt;br&gt;&lt;br&gt;

Plug in USB cable, go to Android settings and enable &quot;USB Tethering&quot; &lt;br&gt;

A reboot should not be necessary.

When restarting AROS, the Smartphone deactivates the connection and to access the network again have to reactivate it before starting the browser. 


===Solving Issues===

[[File:MyArosTCP.png|thumb|Aros network setup diagnostics - why does it not work?]]

* In Network Preferences, have '''only one''' item in the IPv4 Configuration tab 
* If using manual settings, make sure all numbers are correct, especially for IP address of the card/usb (changing the last number in chain of four) 
* For any USB based networking, it is often necessary to save in Prefs/Network, reboot AROS and network support can begin 


* For wired, make sure that the LAN-cable is plugged in before starting the computer 


* If wireless, try getting closer to the router. 
* Switch off the encryption option from your router then try wifi, if successful then your ip/dns is ok. If not then your ip/dns settings are most probably wrong or need to use one or more opendns numbers 
* Replace detachable wireless antenna (best wireless option to buy if you can) with a stronger antenna ie. 5&amp;nbsp;dBi or 7&amp;nbsp;dBi 
* Try with another computer/laptop/machine 

Program Error  C:WirelessManager 

* Test with another OS 
* Check that Wifi works before changeover (if possible) 
* Check that socket and card are working 
* Check if card is too new for laptop (date code on card MMYY blue askey date 2005-2007 etc)   


Are you connecting with the Router ? 

Check with protection off e.g. wps and wep to see if it makes a difference. 


For USB wireless - stopping and starting may be needed...

&lt;pre&gt;

; $VER: AROSTCP-startnet 1.0 (01/08/06)
; AROSTCP-startnet (c) The AROS Dev Team.
;
Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

; stop and restart
execute &quot;sys:system/network/AROSTCP/s/stopnet&quot;

Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

run &lt;NIL: &gt;NIL: wirelessmanager realtek8180.device

&lt;/pre&gt;


What IRQ number is assigned to the device? You can check with Tools/PCITool? 
It's possible the BIOS hasn't set the right IRQ number. If you have a Linux CD/DVD handy, could you check if it boots with the options &quot;acpi=off noapic nolapic&quot;? 


If the following does nothing, this will help us figure out why networking doesn't start automatically at boot

open a shell and run the following commands:

&lt;pre&gt;
echo ${AROSTCP/AutoRun}
echo ${AROSTCP/WirelessAutoRun}
echo ${AROSTCP/WirelessDevice}
&lt;/pre&gt;

Please report the output, typically it will look like this  

# True  (explanation this variable is related to the &quot;Start networking during system boot&quot; checkbox in network prefs) 
# True  ()
# Devs:networks/atheros5000.device unit 0


If there's a problem with the AROSTCP package. What's the output of this?

 ENV:sys/packages/AROSTCP 

should return a string = Sys:System/Network/AROSTCP


By the way, a quicker way to check networking is working would be to run some shell commands such as:


&lt;pre&gt;
ping www.google.com
ifconfig net0
&lt;/pre&gt;


The best way to list the available networks and diagnose / troubleshoot problems with connecting to a wireless network is to run WirelessManager manually. First uncheck the &quot;Start networking during system boot&quot; box in the Network prefs app, then save and reboot. Then run this in a shell:

 C:wirelessmanager atheros5000.device verbose 

or 

 C:wirelessmanager realtek8180.device verbose 

and capture the output 


If the above does not help, could you edit the file SYS:System/Network/AROSTCP/S/Package-Startup, and change &quot;&gt;NIL:&quot; to &quot;&gt;T:wifi.log&quot; on the WirelessManager line and add this as well Wait 5?

&lt;pre&gt;
if ${AROSTCP/WirelessAutoRun} eq &quot;True&quot;
Run QUIET &quot;C:WirelessManager ${AROSTCP/WirelessDevice} &gt;T:wifi.log&quot;
wait 5
EndIf
&lt;/pre&gt;

Then save, reboot and post the log file (T:wifi.log) here.


&lt;pre&gt;

c:wirelessmanager atheros5000.device verbose
Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7)
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'


Then it just sits there. Not sure what a normal dump looks like, I don't see anything that looks wrong in the configuration.
&lt;/pre&gt;

looks like the driver isn't working with that card. Has anyone else successfully used that exact model number (AR2413)?


&lt;pre&gt;

Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7):
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'
*** [wpa_sm_init] sm-&gt;pmksa=02c66fd4 ***
Own MAC address: 00:01:36:15:ae:0c
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
Added interface atheros5000.device:0
State: DISCONNECTED -&gt; SCANNING
Started AP scan for wildcard SSID
MLME: starting scan
MLME: scan channel 1 (2412 MHz)
sana2: sending MLME frame


Then it stops. Does this mean the router is not authorizing this NIC?

IRQ 4 (A)

&lt;/pre&gt;

apparently locking up when the first frame is sent (a scan request).


&lt;pre&gt;

Devs/Networks/atheros5000.device:0
Initializing interface 'Devs/Networks/atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=12):
41 69 72 4c 69 6e 6b 35 39 33 30 30 AirLink59300
PSK (ASCII passphrase) - hexdump_ascii(len=8): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='AirLink59300'
*** [wpa_sm_init] sm-&gt;pmksa=0224e444 ***
Own MAC address: 00:1f:e1:42:e3:7a
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
[eloop_reg_timeout] Timeout is at 1317686594.160000
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
[eloop_reg_timeout] Timeout is at 1317686595.060000
[eloop_reg_timeout] Timeout is at 1317686604.060000
Added interface Devs/Networks/atheros5000.device:0
[eloop_run] Starting
State: DISCONNECTED -&gt; SCANNING
Starting AP scan for wildcard SSID
MLME: starting scan
[eloop_reg_timeout] Timeout is at 1317686594.160001
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.233000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.373000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.513000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.553000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.693000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.013000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.073000
EAPOL: disable timer tick
EAPOL: Supplicant port status: Unauthorized
MLME: scan channel 14 (2484 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.113000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.153000
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.213000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.353000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.493000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.533000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.673000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.993000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686596.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686596.073000
MLME: scan completed

&lt;/pre&gt;

Is your network hidden? If so, did you enable the 'Hidden' checkbox in the network prefs? What distro version are you using? 


&lt;pre&gt;
&quot;ENV:sys/wireless.prefs&quot; looks like this:
network={
ssid=&quot;testadhoc&quot;
key_mgmt=NONE
wep_key0=&quot;12345&quot;
wep_tx_keyidx=0
}
&lt;/pre&gt; 


If your router doesn't broadcast its SSID (hidden), you need to add this option to the network block of the wpa_supplicant.conf on your aros machine and make changes after  # Example blocks: 

 scan_ssid=1

Here's a full description of all the [http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/wpa_supplicant.conf config file options]. 

&lt;pre&gt;
ap_scan=1

network={
ssid=&quot;YOURESSID&quot;
scan_ssid=1
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
group=CCMP
psk=YOURPASSWORD
}
&lt;/pre&gt;

&lt;pre&gt;
filter_ssids=1
ap_scan=2

network={
ssid=&quot;REMOVED&quot;
scan_ssid=1
bssid=REMOVED
priority=100
mode=0
proto=RSN
key_mgmt=WPA-PSK
auth_alg=OPEN
pairwise=CCMP
group=CCMP
psk=REMOVED
}
&lt;/pre&gt;


Error 6: Couldn't resolve host name.

Check Scout -&gt; Devices and look at the device that you are using, in the OCnt column it should state 2 which means AROSTCP and Wirelessmanager are both accessing this driver. If 0 or 1, then uncheck the checkbox in Network prefs for starting networking at boot, save and reboot. Then run this is the shell:

C:WirelessManager realtek8180.device unit 0


some quirks setting up the wireless network as well 

1) it's far better setting up either the wired OR the wireless network adapter as net0:, or weird things happen

2) it's better using fixed IP on the local network instead of DHCP

3) network setting must be placed in network setting panel in /prefs, using the wirelessmanager helped me finding available SSIDs, but not actually connecting to them

once done, reboot.


If previous setup is proving problematic 

&lt;pre &gt;

SYS:Prefs/Env-Archive/Wireless.prefs
SYS:Prefs/Env-Archive/Zune/OWB.config
SYS:Prefs/Env-Archive/Zune/global.config
SYS:Prefs/Env-Archive/AROSTCP/WirelessDevice
SYS:Prefs/Env-Archive/AROSTCP/db/Interfaces
&lt;/pre &gt; 

Make a copy of these files and restore in case of problems. 


Please try this test to check if you can connect to your router, ie established that the WiFi layer is working 

̊̊̊̊Boot with networking disabled, by make sure that &quot;Start networking at boot&quot; in Network Prefs is unchecked (no tick).  
̊ Run this in a shell: C:WirelessManager atheros5000.device VERBOSE
̊If the output of that command is too long to summarise here, you can redirect it to a file by adding &gt;RAM:wifi.log to the end, then attach or paste that file here.


try running &quot;status&quot; in the shell and check that AROSTCP is listed/running
If AROStcp is not showing, then AROSTCP is not running. attempted to start it by clicking Use or Save in network prefs, or checking the &quot;start networking at boot&quot; box or typing into a shell. 

 Execute SYS:System/Network/AROSTCP/s/startnet

(run Status again afterwards).


The &quot;cannot resolve hostname&quot; will appear if you are blocked on the wifi network by the router as well as aros not being able to assign correct network address.

One way of testing this might be to disable the firewall in the router. you might also check the router how it sees the attempts aros do to speak to it. The easiest way to do that would be to manually give aros an IP number in the routers accepted range. and see if it shows up at all within the router.


Tests that can be undertaken to determine correct settings and functions 

 pciinfo
 sanautil -d broadcom4400.device status

&lt;pre &gt;
 ping &lt;router-address&gt; e.g. 192.168.0.1 (aka inet) or 80.237.146.33 (www.amiganews.de) 
 ifconfig net0
 ifconfig net0 up
 extras:networking/utils/sanautil/sanautil -d atheros5000.device status
 WirelessManager atheros5000.device verbose &gt;RAM:wifi.log
 ;to send the log to RAM disk to be read easier or if detected, 
 Run WirelessManager atheros5000.device &gt;NIL:
 Run WirelessManager atheros5000.device ssid=&quot;mynet1&quot; &gt;NIL: 
 C:WirelessManager realtek8180.device unit 0 
&lt;/pre &gt; 

Please look at the task list in Scout, and check if WirelessManager and AROSTCP are running. Also look at the device list in Scout to check if realtek8180.device is open. 


start tools/debug/sashimi, maybe it shows some debug messages when disconnection happens.


Firstly, let's take a look at what your setup most likely looks like, assuming you use a router. See diagram below: 

&lt;pre&gt;
Internet &lt;---------&gt; home router &lt;---------&gt; computer 
-----------external IP------------------internal IP-------------
&lt;/pre&gt;

Okay, so what am I trying to show you with that diagram. A few things. Firstly, the IP address that connects you to the Internet is not the same one that connects you to your router. What happens is that your computer doesn't have a direct connection to the Internet, instead your router connects to the Internet, and your computer connects to the router.

You can see the external and internal IP addresses in these example settings...

* Default Gateway : 76.91.64.1 (external IP for ISP/Internet host)
* IP Address : 76.91.71.184 (external IP for home router)

* IP Address : 192.168.0.1 (internal IP for home router)
* Address = 192.168.0.161 (internal IP for computer)

As you can see, there are two internal IP addresses and two external IP addresses. This is because there is a client/server relationship, effectively one address is for the service (server) and one address is for the device trying to access that service (client).

The server addresses in your case are 76.91.64.1 (your ISP's address, serving the Internet), and 192.168.0.1 (your home router's address, serving your home network). The term gateway applies here, they are your gateway to those services.

Subnet masks are used along with IP addresses to determine which IP addresses are allowed access to a network. I did learn the more in-depth rules about subnet masks once (watched a CCNA vid), but I've forgotten about it. The basic level of understanding you'll need is easy to remember though. A subnet mask value of 255 means that portion of the IP address must stay constant, whereas a subnet value of 0 means any unassigned value up to 255 is allowed in the IP address.

By far the most common subnet value is 255.255.255.0. What this means is that the first three parts of the IP address you use to connect to a service must stay the same as the server/gateway address, and only the last section can change.

So if your router's internal IP address is 192.168.0.1, and the subnet mask is 255.255.255.0, the only addresses that will be allowed to be used on that network are between 192.168.0.2 and 192.168.0.255 (I think 192.168.0.0 is reserved for other uses).

Final point to make is about DHCP (a.k.a. dynamic IP) vs static IP. A server/router using DHCP gives a device that connects to it an address within the acceptable range. It usually starts with the lowest numbered free address, so with your router it'll give the first device that connects to it 192.168.0.2, the next device 192.168.0.3, and so on. Static IP addresses are where you set the IP address you want to connect with in advance. 

When using static IP addresses on a router where DHCP is active, it's good to use a high number to avoid conflicts with other devices that are connected to your network, to reduce the risk that both devices will try using the same IP. That's why your current choice of 192.168.0.161 is good, unless you have over 159 devices connected on your current network!


Okay, so what's the next step. Well, if you can use ping, I'd suggest pinging 192.168.0.1. If you get a positive response it means you're connected to your router, if you don't get a response it means the connection between your router and your computer is at fault.

Documentation on configuring the AROSTCP environment further can be found [http://en.wikibooks.org/wiki/Aros/User/Networking here] 


===File Sharing===

As AROS knows only a few filesystems (FFS, OFS, SFS, PFS (amiga only), FAT12, 16, 32, Microsoft NTFS (windows), UDF (Blu-ray)). 
The others in regular use like MacOSX hfs+, Linux ext2/ext3 and ext4, Haiku BeFS provide a problem in transferring files. 

Linux can access SFS partitions but it needs to be compiled. The latest full source are [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ here]. It compiled fine with a 2.6.30 kernel in Puppy Linux 4.31. 

An alternative, is to use a FAT32 partition to share. Setup a 4G FAT32 partition using HDToolbox for sharing, and the rest of the space as SFS for an Aros install. It works very well. 

Files could be transferred via TCP internet network. 


====SMB2/3====

With Windows you can share one folder or all folders of the &quot;Public&quot; user.

On Windows what is important is to enable sharing (Network and Sharing Center).

AROS Mountlist should look lke this 
&lt;pre&gt;
Handler = L:smb2-handler
StackSize = 65536
Priority = 5
GlobVec = -1
ACTIVATE=1
Startup = &quot;smb://UserAcc:password@PCShare/Sharefolder&quot;
&lt;/pre&gt;

which could also be
&quot;smb://UserPC:password@192.168.x.x/Public&quot;
or
&quot;smb://UserPC:password@Name-PC/Public&quot;

so
&quot;smb://UserPC:password@192.168.1.158/Folder&quot;
or
&quot;smb://UserPC:password@Name-PC/Folder&quot;


After you have configured a share generates a DOSDrivers it is named &quot;SMB0&quot; which includes the setting, and at each reboot it is Mounted. You can still delete the DOSDriver by hand, is located in Storage/DOSDrivers, the file &quot;ServerAutoMounts&quot;, in ENV:AROSTCP which indicates the DOSDriver to be mounted, should also be deleted. 
The per-mount files are written to ENV:SMB or SYS:Storage/DOSDrivers. There is also additional file ENV:AROSTCP/ServerAutoMounts which states what will be presented to the end user. 


====Old SMBFS====

e.g. to connect to a NAS share such as \\NASBOX\Shared use -:

SMBFS WORKGROUP=&lt;YOUR WORKGROUP NAME&gt; VOLUME=&lt;AROS volume name to use&gt;: SERVICE=&lt;UNC Path to connect to&gt;

SMBFS WORKGROUP=MYNET VOLUME=Shared: SERVICE=//NASBOX/Shared

And you will then have an icon appear on your desktop for the volume name you have chosen. 


You can put the above script into wbstartup or  

give it an icon, change it to a 'project' and give it the default tool c:iconx 

Open a shell and type copy sys:script.info &quot;sys:wbstartup/YOURSCRIPTNAME.info&quot;

This should create an icon for your script file.

Now right-click on your script and select 'information'.

Change 'tool' to 'project', put 'c:iconx' into the 'default tool' box, click save 

The reason being that scripts need to be opened with 'execute SCRIPTNAME' (or 'iconx') whereas the programs started from wbstartup are opened using 'run PROGRAMNAME'. It's the same as trying to start a command-line tool from the workbench by double-clicking it.


====Setup ISO images within AROS====

Use [http://archives.aros-exec.org/index.php?function=browse&amp;cat=driver/storage DiskImage] which supports many cd image formats ISO, CCD, MDF/MDS, CUE/BIN, NRG and UIF. To mount CD or DVD images use below....

&lt;pre &gt;
# Rename your iso 'Unit0' (note no extension).
# Do 'View/All files' on you Aros partition. You should now see a folder called 'Diskimages'. Copy your renamed iso to there. 
(Alternatively, you could type at the shell 'assign FDSK: xxx', where xxx is the location of your iso.) 
# From the shell, type 'mount CD0:' and the iso should appear on the Wanderer desktop. You can now access it like a real disk.
&lt;/pre &gt; 

 assign devname: dismount 
 Assign DOSVOLUME: remove
 [http://aminet.net/package/disk/misc/unmount-0.1 unmount] most filesystems work but SFS lacks support for ACTION_DIE packet 

If you are using an IcAros install, the startup scripts are set up to wipe the Diskimages directory on boot, so its worth keeping a second copy of the iso somewhere else. Alternatively, you could set up extra mountlists for additional iso images. I've made a file called iso1 in the Aros:devs directory that contains the following text:

&lt;pre&gt;
/* Entry for ISO image */

ISO1:
FileSystem = cdrom.handler
Device = fdsk.device
Unit = 1
LowCyl = 0
HighCyl = 0
Surfaces = 1
BlocksPerTrack = 1
DOSType = 0x41434400
Activate = 1
#
&lt;/pre&gt;

Then I just need an iso called 'Unit1' (corresponding to the 'Unit = 1' entry in the mountlist) in Diskimages (or wherever I assign FDSK: to) and to mount I type in at the shell:

 Mount iso1: from devs:iso1

Of course, if you create mountlists for ISO2, ISO3:, etc. (with the corresponding change to the 'Unit = ' line) you can have as many isos mounted as you wish. I just call mine ISO1: etc. to distinguish them from the real CD drives 


==Video Guides==


Video demonstrations and tutorials covering:

:00. '''Introduction''' 
::[https://www.youtube.com/@jamesmattson6813/videos Various Aros Installs], 
::[https://www.youtube.com/embed/j8EmSEby0Rg AROS repo in gource, view of AROS dev commits from 1997 to 2025], [http://www.youtube.com/watch?v=Vx_zqlBow40&amp;feature=related Gource view of AROS 1997 up to 2009], 
::[http://www.youtube.com/watch?v=s1RsvEm7UrU Why an Amiga OS in 2011], 
::[https://www.youtube.com/watch?v=1W886mheV74&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Johan Grip on early days of AROS x86], [https://www.youtube.com/watch?v=mXaKDhtTTqQ&amp;t=14s&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Michel Schulz on Aros and PiStorm], 

:01. '''Installation'''
::[https://www.youtube.com/watch?v=M7YjufrJqDs Aros One install], [https://www.youtube.com/watch?v=iIMguHTdC5E Aros One USB install], [https://www.youtube.com/watch?v=ZNXauy5m5Wc Aros One install], [http://vimeo.com/11013489 Modify Grub boot], 
::[http://www.youtube.com/watch?v=wyQVeyXIywc&amp;feature=channel iMica Silent Pt3], [http://www.youtube.com/watch?v=o2AnkoflY14 Wipe whole drive and Install - warning loss of data on drive], 
::[http://www.youtube.com/watch?v=OVXm6_-witQ VirtualBox install], [ VMware install], 
::[http://www.youtube.com/watch?v=0k2PEmT8I14 Broadway AROS Install], 
::[https://www.youtube.com/watch?v=PtDiXhjSIfs Is Aros Icaros a choice?], 
::[ driver install], 
::[http://www.vimeo.com/10491104 HDAudio install but needs account], [], 

:02. '''Amiga Basics'''
::[http://www.youtube.com/watch?v=TY8mWxwzH5o Screens tutorial], 
::[https://m.youtube.com/user/AMIGASYSTEM/videos General], [ Dos Scripts tutorial], [http://www.youtube.com/watch?v=hPT7SmVEpjc OS 1.2], [http://www.youtube.com/watch?v=n6kX3FqH8Ww&amp;feature=related OS 1.3], 

:03. '''Customisation demos'''
::[https://www.youtube.com/@AMIGASYSTEM/videos Prefs tutorial], [ Decoration tutorial], [http://www.youtube.com/watch?v=Dn5C8G3aDXU Scalos], 

:04. '''Setting up''' internet access and surfing the web, FTP, IRC and Mail apps 
::[ Network Prefs], [ AirCOS tutorial], [ jabberwocky tutorial], 

:05. '''Native bundled Games and Applications''' 
::[http://www.youtube.com/watch?v=aYlFv2B-VXc 3D Games], [http://www.youtube.com/watch?v=MXK7wwhd-R0 Latest Games], [http://www.youtube.com/watch?v=RUgiVThv23Q&amp;feature=mfu_in_order&amp;list=UL PrBoom GL], [http://www.youtube.com/watch?v=0s7u8TPy7V4 Assault Cubes], [http://www.youtube.com/watch?v=fih6aCXKeqs Cube 2], [http://www.youtube.com/watch?v=-X0ay0MGOms DosBox on Aros], [http://www.youtube.com/watch?v=7nKduDjf14k Oct 2010], 

::[http://www.youtube.com/watch?v=FziV2z_uxnQ Apps Pt 1], [http://www.youtube.com/watch?v=xs37_nfa5CI Apps Pt 2], [http://www.youtube.com/watch?v=Bn59_VvbQR0&amp;feature=related Apps Pt 3], 
::DOpus4 [http://www.youtube.com/watch?v=aSRybWjrrME DOpus 4], 
::Milkytracker [http://www.youtube.com/watch?v=VxBOEPzpdKg&amp;feature=related Laying Down Base Tracks], 
::[http://www.youtube.com/watch?v=k2uKQ0-ieOE Audio Evolution 4 in action], [http://www.youtube.com/watch?v=Zq4r9k0_jZI Quick Videos], 
::[http://www.youtube.com/watch?v=gGKCFZcIc0I&amp;feature=related ScreenRecorder], [http://www.youtube.com/watch?v=974c2e-Fqak&amp;feature=related TV out Tests], 
::[http://www.youtube.com/watch?v=fjq8ct5d5IY AmiFIG], [http://www.youtube.com/watch?v=h0rHvPhYJo4&amp;feature=youtu.be ZuneFIG], 
::[http://wiki.povray.org/content/Documentation:Tutorial_Section_1 POVray Tutorial 1], 
::[http://www.youtube.com/watch?v=Jk-ZNLfJsvQ pt 1, jan. 2008], [http://www.youtube.com/watch?v=nWRy33g1R7Y pt 2, feb. 2009], [http://www.youtube.com/watch?v=r5PbhCtm4vE pt 3, feb. 2010], 

::[https://www.youtube.com/watch?v=G7_FJUoQ89o Hollywood programming], [], [], [],

::[], [], [], 
::[], [], [], 
::[], [], [], 


:06. '''Commercial software available'''
::[http://www.youtube.com/watch?v=fKXY9B4R43s AntiryadGX 3D Game Editor], 
::[http://www.youtube.com/watch?v=TMS9NDzwm5U BOH indie Game], 

:07. '''Running classic amiga apps and games''' 
:: Amiberry [], [], 
::[http://vmwaros.blogspot.com/2008/11/introducing-amibridge.html Intro Amibridge], [http://www.youtube.com/watch?v=ee2PWvCZeLo Old Amiga Apps], [http://www.youtube.com/watch?v=ee2PWvCZeLo Why Janus UAE is good], 
::[https://www.youtube.com/watch?v=VhlsNSYSuDg DPaint tutorial]

::[http://vmwaros.blogspot.com/2009/11/can-icaros-play-my-amiga-games-and-why.html Play Amiga Games], [https://www.youtube.com/watch?v=XTaZCNOvCnE], 
::[http://www.youtube.com/watch?v=tMehS77LXQ4 Pagestream Introduction], [http://www.youtube.com/watch?v=284-w3hTzII Pagestream Tutorial 1], [http://www.youtube.com/watch?v=mlwEGwhZzl4 Pagestream Tutorial 2], 
::[http://www.youtube.com/watch?v=iIcrIjPOctc Catweasel Mk4 PCI Part 1] and [http://www.youtube.com/watch?v=BaitHeL6bEA Part 2], 

:08. '''Misc and History'''

::[http://www.youtube.com/watch?v=d6mDXKU29w0 Mum uses old AmigaOS Workbench 1.1 (1986)], [http://www.youtube.com/watch?v=DaRkacQ-YMg Why an Amiga 500 (1987)], [http://www.youtube.com/watch?v=k5CYsgVCzYY an Amiga 2000 (1987)], 

:09. '''Misc Shows and Events'''
::[http://www.youtube.com/watch?v=klgVSWKs4kE VCF 2010], [https://www.youtube.com/watch?v=eQ3d5qR-Hv8 24:06 Jason McMullan at amiwest 2012 about AROS], [https://www.youtube.com/watch?v=jpQO7XSfAv4 Aros SMP multi core amiwest 2013], [], [https://www.youtube.com/watch?v=gFRtAAmiFbE], [https://www.youtube.com/watch?v=DjdUEyjx8GM], [https://www.youtube.com/watch?v=ydYDqZQpim8], [], [https://www.youtube.com/@uminekoshouten/featured], [https://www.youtube.com/shorts/NfoY023w-vE], 

:10. 
::[https://www.youtube.com/shorts/6qJTNW4-6GY]


===History===

The project was originally started by a small group of Amiga [http://www.amigahistory.co.uk/aros.html enthusiasts] in 1995. These individuals were mainly computer-based college university students at the start, though that student trend has diminished since. An interview with Aaron Digulla [http://arosshow.blogspot.com/2006/12/interview-with-aaron-digulla-who.html here] 

* 1992 Commodore folds 
* 1996-1998 much of the early years was concerned with exec, dos and intuition libraries. 
* Early 1999, Haage &amp; Partner used parts of the AROS code in AmigaOS 3.9. 
* March 2001, floppy disk images of AROS became available. 
* Early 2002, AROS changed its name from Amiga Replacement Operating System to Amiga Research Operating System 
* June 2002, AROS devs decided to use Zune (MUI 3.8 rewrite) as the GUI system. 
* November 2002, Eric Schwartz drew Kitty for AROS usage. 
* Early 2003, AROS.org underwent a graphics facelift. 
* Late 2003, GCC C compiler arrived. 
* Early 2004, Aros-Exec opened. 
* Early 2005, Aros Max bootable CD arrived. 
* Late 2005, SFS filesystem ported and allowed fast access to apps and network support arrived 
* Early 2007, AROS.org underwent another graphics facelift. 
* Mid-2007, AROS changed to AROS Research Operating System after A.Inc. sued Hyperion with a trademark violation. 
* Late 2007, the hard disk installer added and VmwAROS (later called Icaros Desktop) distro launched. 
* Early 2009, Our first usable web browser (OWB)
* September 2010, first wireless support appears and AspireOS started as a distro 


* Early 2012, the first paper-cut bugfix and Fab's Odyssey Web Browser ported 
* Early 2017, work started on utilising the addition cores on modern CPUs starting with the 64bit x86 PC version  
* Mid-2017, m68k port optimized for the Vampire 2 / Apollo accelerators (68080 AMMX FPGA) 
* 2018 The old AROS Exec website closed and a new one opened 
* 2019 AROS One x86 32bit distribution started and now with USB install version 
* Early 2021, backport of more features of 32bit PC ABIv1 into 32bit PC ABIv0 (Aros One 1.5 and above) 
* 2025 year of 64bit pc builds and porting 32bit applications to 64bit ABIv11
* 2026 update of [https://www.youtube.com/watch?v=6FKTL068ULM&amp;pp=ygUPYXJvcyBhbWlnYSAyMDI2 nvidia nouveau driver for 64bit PC] 


===Bounties===

To help inspire developers with both ideas and monetary incentives, rewards are offered for the successful completion of &quot;bounties&quot; (requests for missing/new functionality) chosen by the community and handled by [http://power2people.org power2people] (formerly done by TeamAROS). A monthly option is [http://www.power2people.org/funds/aros/ here].


Future goals for AROS include expanding its underlying retargetability to support even more diverse architectures, provide memory protection features and user level file security, SMP and many other wonderful features missing from AmigaOS &amp;mdash; while still providing as much source level compatibility as is possible (however it is accepted that to achieve some goals code certain things may require a little recoding).


[http://www.ohloh.net/p/aros/contributors Developers] come and go as with any open source effort and we would like to thank them for their efforts... 

;1996-2000:In DigullaA (coordinator), GripJ, TempletonI (BSD), SchulzM, RittauS, voordenDagL, HolmM, JohanssonT, VanIngelgomH, SteigerwaldM, BortasP, deJongK, AlfredssonJ, InnocentiB, 

;2001-2005:In [http://chodorowski.com/adam/aros.html ChodorowskiA], StegerG, BergerS, HeutlingS, AlemagnaF (gcc), VerhaegenS (rexx), KielH, MatheussenKS (CAMD), SzczygielskiP, ErikssonP, LeCorfecD (Zune), BauerS (Zune), FurlongW, GustafssonJ, AndrewsN, CafferkeyN, GierichM (jpeg), PattonJ, ParsonsM, DietrichJ, SeilerT, BischoffL, LorentzenNH, AdamO, BerglundH, SmithP, HolmenD, BlomM, 

;2006-2010:In FedinP, RusslerM, SzymczykS (owb), SmiechowiczK (openGL), WeissM, NorrisR, BrunnerO, WiszkowskiT, GreppinA, [http://www.fukt.bsnet.se/~bearsoft/ Bearsoft Björn Screwelius], ErbY, CharletF, HodgesC, [http://aros-exec.org/modules/newbb/viewtopic.php?topic_id=4819&amp;forum=18&amp;post_id=43103#forumpost43103 HokstadV], McMullanJ (m68k), WilenT (m68k), 

;2011- :In MuijzenbergPHvanden, ALB42, JonesEM, weiju, DizzyofCRN, wawa, miker, 


* 1996 - The linux hosted version for i386 was the first to arrive 
* 1998 - i386, The native version for i386-based PC AT computers and compatibles.
* 2004 - x86/64, The native version for 64-bit (x86_64, amd64) PC computers.
* 2008 - sam440/ppc, The native version for Sam440EP, Sam440EP Flex and Sam460ex computers.
* 2009 - efika, The native version for PowerPC Efika computers.
* 2010 - m68k, The native version for m68k Amigas or WinUAE
* 2013 - raspi/armfh, early native version for ARMv6 based Raspberry Pi computers.
* 2017 - x86/64bit smp 


Debugging capture serial debug at all (especially with sysdebug=all or --sysdebug=all) to see it displayed on screen 

* yes, usb -&gt; rs232 adapters can work most of the time, some of the cheapest ones are not fully compatible with all rs232 devices to capture to another device 
* you will need a null modem cable (or a null modem adapter usually female to female) in addition to the usb -&gt; rs232 adapter (usb adapter is a normal modem ie. the pins are not crossed over) 

Normal modem cable - straight connection DCE 
&lt;pre&gt;
Pin 2 -&gt; Pin 2  RXD
Pin 3 -&gt; Pin 3  TXD 
Pin 5 -&gt; Pin 5  GND
&lt;/pre&gt;

Null modem cable connections DTE 
&lt;pre&gt;
Pin 2 -&gt; Pin 3
Pin 3 -&gt; Pin 2
Pin 5 -&gt; Pin 5
&lt;/pre&gt;
(9pole SUB-D)


&lt;pre&gt;
serial  ser: (amiga/aros)  tty2 tty1USB0 (linux)  COM1 (windows)  (depends on the os being used) 
speed baud transfer rate 9600 38400     lower baud might be more successful 
data bits 8
stop bits 1
parity none
handshaking flow control - none xon/xoff (most likely)  rts/cts  dsr/dtr (pins not connected so should not work) 
&lt;/pre&gt;


*You cannot use compiled aros X86-64 bit software (when ready) on aros X86 32bit. PPC compiled software on X86 and so on. 
*68k is tested with the UAE emulator (WinUAE) but some tests are done on native 68000 based Amigas and others. 
*PPC support is very limited to certain devices. 


If you use the WBStartup, you have to delete the other icons in the folder (readme etc..) and you have to add in the Icon Tooltype the parameter DONOTWAIT

If you use user-startup instead, you need to add the attached command &quot;after assignment to LUA&quot;
C:WBRun DH1:Extras/Utility/WeatherBar/WeatherBar &gt;NIL:
Change the command to match your WeatherBar path.

&lt;pre&gt;
PATH sys:Utilities/WeatherBar ADD
run &gt;nil: lua:amilua weatherforecast.lua
&lt;/pre&gt;

To enter data your Country or City, ist with city_id numbers can be found [http://bulk.openweathermap.org/sample/city.list.json.gz here] or you need to go to [https://www.bbc.com/weather BBC Weather], once you type the name of your city or town in the appropriate tab, and press enter, the 7 numbers to be added in the &quot;WeatherBar&quot; will appear on the Browser url address bar above 


Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251 – Cyrillic (Amiga)
    ISO-8859-1 – Western European
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2 – Central/East European
    ISO-8859-3 – South European
    ISO-8859-4 – North European
    ISO-8859-5 – Slavic languages
    ISO-8859-9 – Turkish
    ISO-8859-15 – West European II
    ISO-8859-16 – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)
&lt;/pre&gt;


Icaros 2.3 USB image needs a header stripped so it can work correctly 
 dd bs=512 skip=1 status=progress if=icaros_light_2-3-0_pendrive.bin of=/dev/sdxy &amp;&amp; sync


Scalos 
&lt;pre&gt;
-------------------------------
{ &quot;STRING&quot;,		&quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;,

HALIGN		LEFT | CENTER | RIGHT

VALIGN		TOP | CENTER | BOTTOM

STYLE		NORMAL | BOLD | ITALIC | BOLDITALIC

FONT		// font specification - format: &quot;fontname.font/size&quot;

-------------------------------
arguments for STRING SRC

&quot;diskstate&quot;,		
&quot;diskusage&quot;,		
&quot;diskusagefree&quot;,	
&quot;diskusageinuse&quot;,	
&quot;diskusagepercent&quot;,	
&quot;fibfilename&quot;,	
&quot;filecomment&quot;,	
&quot;filedate&quot;,		
&quot;fileprotection&quot;,	
&quot;filesize&quot;,		
&quot;filetime&quot;,		
&quot;filetypestring&quot;,	
&quot;iconname&quot;,		
&quot;linktarget&quot;,		
&quot;plugin&quot;	pluginname &lt;optional plugin arguments&gt;
&quot;versionstring&quot;,	
&quot;volumecreateddate&quot;,	
&quot;volumecreatedtime&quot;,	
&quot;volumeordevicename&quot;,	

-------------------------------

arguments for HIDE

&quot;novolumenode&quot;,	
&quot;isempty&quot; (some STRING)	

-------------------------------

all internal commands:

&quot;about&quot;,		
&quot;backdrop&quot;,		
&quot;cleanup&quot;,		
&quot;cleanupbyname&quot;,	
&quot;cleanupbydate&quot;,	
&quot;cleanupbysize&quot;,	
&quot;cleanupbytype&quot;,	
&quot;clearselection&quot;,	
&quot;clone&quot;,		
&quot;close&quot;,		
&quot;copy&quot;,		
&quot;cut&quot;,		
&quot;delete&quot;,		
&quot;emptytrashcan&quot;,	
&quot;executecommand&quot;,	
&quot;formatdisk&quot;,		
&quot;iconify&quot;,		
&quot;iconinfo&quot;,		
&quot;lastmsg&quot;,		
&quot;leaveout&quot;,		
&quot;makedir&quot;,		
&quot;open&quot;,		
&quot;parent&quot;,		
&quot;paste&quot;,		
&quot;putaway&quot;,		
&quot;quit&quot;,		
&quot;redraw&quot;,		
&quot;redrawall&quot;,		
&quot;rename&quot;,		
&quot;reset&quot;,		
&quot;selectall&quot;,		
&quot;showallfiles&quot;,	
&quot;showonlyicons&quot;,	
&quot;shutdown&quot;,		
&quot;sizetofit&quot;,		
&quot;snapshot&quot;,		
&quot;snapshotall&quot;,	
&quot;snapshotwindow&quot;,	
&quot;unsnapshot&quot;,		
&quot;update&quot;,		
&quot;updateall&quot;,		
&quot;viewbydate&quot;,		
&quot;viewbyicon&quot;,		
&quot;viewbysize&quot;,		
&quot;viewbytype&quot;,		
&quot;viewbytext&quot;,		
&lt;/pre&gt;


{{status|50%}}
{{BookCat}}</text>
      <sha1>34huewufuidc2ptvoztufx5bhwc9vsr</sha1>
    </revision>
    <revision>
      <id>4669849</id>
      <parentid>4669763</parentid>
      <timestamp>2026-09-13T07:47:25Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669849</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="138214" sha1="ej47wj00qh2qebzd50avj54hioqfnn2" xml:space="preserve">{{ArosNav}}

==What is AROS==

Google translation 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=nl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Dutch], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Italian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=da&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Danish], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Polish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ja&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Japanese], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ko&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Korean], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Portuguese], 


*Computer Hardware
*AROS (operating system)
*Applications and Games
*User


[http://www.osnews.com/story/15819 AROS] is one of the intermediate levels between the computer hardware and the user. It is an open-source, clean-room implementation of AmigaOS 3.x that can be run on many different computer architectures. It runs primarily on PC x86 32bit and 64bit but also on amiga motorola 68k and compatibles, some ARM like the Pi and Apple Silicon, RISC-V and some old PowerPC. 

This page will cover enough to be able to write the downloaded image to your preferred media, to run a LiveUSB, LiveCD or LiveDVD on your office/home PC (Live meaning you can test without changing your existing setup) and, ultimately, to use it.  

Intel / AMD PC hardware support mostly covers the years 2000 to 2024. At the moment, AROS is '''not''' recommended to be '''installed''' on a working vital data holding machine. Instead, writing to and booting from a '''USB stick''' could be a much better option. 

AROS is an hobby OS and can co-exist with Windows(TM), MacOSX(TM), Android(TM) or Linux(TM) and act as an alternative. 
Unfortunately, Aros has few developers so upgrades and improvements can take [https://sourceforge.net/p/aros/mailman/aros-cvs/ time to appear]. 

AROS core is now [http://en.wikibooks.org/wiki/Aros/Developer/IncompleteAPIs ~80%] finished and is usable, so keep in mind that the software is still considered ALPHA/BETA and in constant development. Currently AROS is fun to play with on a curiosity level, but it is also interesting to program. AROS has some multimedia features and has internet access.  

Most importantly, use AROS to its maximum potential as it stands now, find ways to have fun with it and share your experiences. 


Good Sites to visit 

: [https://www.arosworld.org/home.php Aros World User forum] 
: [https://arosnews.github.io/ AROS News]
: [https://www.facebook.com/ArosWorkshop/ Aros Workshop], 
: [https://www.osnews.com/topic/amiga-aros/ OSNews] 
: [https://www.reddit.com/r/aros/ Reddit]


: [https://archives.arosworld.org Aros Archives] 
: [https://aminet.net/ Aminet]
: [http://www.amiga-news.de/en/ English translation of German site]


: [https://aros.sourceforge.io AROS] with [https://aros.sourceforge.io/download.html ABIv1 downloads] 
: [https://github.com/aros-development-team/AROS Aros ABIv1 Codebase]
: [https://github.com/aros-development-team/AROS/issues register ABIv1 issues] and [https://sourceforge.net/p/aros/bugs/ old defunct bugs notification site] 


: [https://sites.google.com/view/arosone Aros One x86, x64] 
: [https://tinyarosdistro.flazio.com/ Tiny Aros x86 and x64]
: [https://arosnews.github.io/aros-portable/ AROS portable USB3 stick images of hosted Aros One x86 and x64 on debian] 
: [http://vmwaros.blogspot.com Icaros Desktop x86 now on sabbatical, very old edition] 
: [https://sites.google.com/site/arosaspireone AspireOS, of the netbook Aspire One, very old edition] 
: [https://github.com/deadwood2 Deadwood's builds], [https://www.axrt.org/download/aros/v11/ v11 64bit PC builds], [https://axrt.org/downloads-aros Updated i386 32bit PC builds], 
: [https://github.com/ezrec Ezrec x86 m68k mirror of old svn version]


: [http://arosalive.blogspot.co.uk/p/10-basic-aros-how-tos-tutorials.html Basic How To guides] 
: [http://arosgamer.blogspot.co.uk/ AROS Playground], [http://thewetmachine.net/tag/aros/ Jess Wet Machine], [https://aroshacking.wordpress.com/ Jon Robertson's AROS Experiences and FPC Free Pascal], [], 
:[http://www.apollo-accelerators.com/ Apollo Accelerators m68k], [http://www.amigablogs.net/ Amiga Blogs], [http://blog.a-eon.biz/blog/ Trevor Dickinson blog], 


: [https://forum.amiga.org/ Amiga OS AOS 3.x forum] 
: [http://eab.abime.net/ EAB Amiga] 
: [http://www.amigaworld.net/ AmigaWorld] 
: [http://www.ppa.pl/ Polish Amiga Like News] 
: [http://www.apollo-core.com/ Apollo Forum] 
: [https://amigaalive.blogspot.com/ AmigaAlive]
: [https://www.amigalove.com/software Disk Mags]
: [https://amigachristmastree.ultimateamiga.com/ Xmas Amiga Game Jam]
: [https://www.reddit.com/r/amiga/ Amiga]


== Distributions aka Distros ==

For end users there are distributions (ready made with selected apps aiming to be easy to use), mostly created and maintained by one person in their own workflow/style. They reuse the nightly boot compiles to suit their needs and possibly other end users. You are free to create your own if required. 

* For native 64bit Intel/AMD: [https://sites.google.com/view/arosone Aros One x64], [https://tinyarosdistro.flazio.com/ Tiny Aros],
* For native 32bit Intel/AMD which will run on 64bit machines: [https://sites.google.com/view/arosone Aros One x86], [https://www.tinyaros.it/ Tiny Aros], 
* For native 68k [https://sites.google.com/view/arosone Aros One m68k], [http://www.aros-platform.de/ AROS Vision], 

'''Please, keep in mind that the distros listed above use a different ABI (abi v11) , which is NOT binary compatible with the official ABI V1.'''
* For hosted Linux usb drive image [https://arosnews.github.io/aros-portable/ x64 Debian hosted version of Aros One], 
* For hosted ARM there is [https://github.com/jonx/AROS-AArch64/releases alpha for Apple Silicon] and [https://aros.sourceforge.io/nightly1.html RaspberryPi 3 raspi-aarch64-system native 64bit] 


AROS was originally developed on Linux but can run on an Intel-based Linux distro as an app. As time has gone on, it can be run as an app on many more operating systems (Windows, FreeBSD, Linux and limited on MacOS). This may sound strange: an OS running on top of another OS. 
Basically, this is to take advantage of drivers (audio, internet, graphics, etc.) and compiler environments, in the existing OS, with which people may be already familiar. The term we use for what AROS does is &quot;Hosted&quot;. 

AROS Native is the term coined to describe AROS being run without any OS underneath it. It runs alone just like AmigaOS(TM) did. As this version does not benefit from &quot;Hosted&quot; drivers, dedicated ones have to be ported/written. Hence the smaller range of supported hardware / peripherals. We have other pages highlighting this support 


AROS is open source so basically everyone can take part. The source is public on github and there are new commits most days. AROS is automatically compiled daily, result are the nightly builds hosted on Sourceforge. The nightly builds are only used for testing changes, testing software and the starting point for distribution maintainers or even your own distribution. They are very basic, miss some functionality and apps like web browsers and generic general appearance which can be changed. 

* The [https://sourceforge.net/projects/aros/files/nightly2/ Nightly2], [http://aros.sourceforge.net/download.php nightly builds File Release Service] or [http://aros.sourceforge.net/downloads/ Sourceforge Project Web builds] are made automatically every night directly from the Github and in the past, SVN (Subversion) tree and contain the latest code for the AROS operating system. It should be noted that the builds have not been tested in any way and can be horrible broken. 

*ABIv11 offspring of 64bit PC ABIv1 i.e. another PC 64bit build 
*ABIv1 standard for most nightly builds, it is where the most work is done by developers 
*ABIv0 standard for PC 32bit intel / amd PC distributions for historic reasons 


==Media==

AROS media tends to boot in this tier list of media types, first internal HDD SSD, CD DVD drive, and finally usb drive (last two can depend on bios boot order) 

* USB .VHD 

[https://sites.google.com/view/arosone Aros One x86 and x64], with md5 below 

&lt;pre&gt;
0a656d53a9c902e9934000d8392e30ec *ArosOne-USB-1.3-64Bit.zip
7dd7119ab3e56d75ee852c137226b4d7 *ArosOne-USB-v1.2-x86_64-v11.zip
cf906eeaad4a83b3520b1896bdc6b0d3 *ArosOne-USB-v1.1-x86_64-v11.zip

e2eb8fe8cfd61c567b0152a61cf85251 *ArosOne-x86-v2.8-USB-IMG.zip
559909c75c2f56472c74267a7d075355 *ArosOne-x86-v2.7-USB-IMG.zip
93da5898508c1a8c05bb8991ab7bd117 *AROS One Image-USB-2.4.zip
59fcabd7090e47f12d54f7eb78cf0f45 *ArosOne-x86-v2.2-USB-Image.zip
24fb8de726ae8fc5fe5bac6d30f03dc5  ArosOne-x86-v2.0-USB-Image.zip
f3d725e990072edce633b59747911b6b  ArosOne-x86-v1.8-USB-IMG.zip
e089a24ae310e92fcc407a0125602ce8  Aros-One x86-IMG-USB-v1.6.zip
&lt;/pre&gt; 


[https://tinyaros.flazio.com/ Tiny AROS]

22bc993625b7c75b17263c0cc7e7baaa *Tiny Aros_copy.vhd (March 2024) 


There is usually a vhd image inside the zip that can be written to USB sticks which is so much faster than the old ISO written to physical CD DVD method. This .vhd can be written to an USB stick / ssd with these pieces of software below but it will erase the previous contents from the usb 

Windows - [https://www.raspberrypi.com/software/ RPi Raspberry Imager, use custom and see all files], [https://hddguru.com/software/HDD-Raw-Copy-Tool/ HDD-Raw-Copy-Tool], [https://rufus.ie/ Rufus up to version 3.20 may work with VirtualBox HD vhd images with Win7 but not some Rufus 4.x versions], [https://etcher.balena.io/ Balena Etcher but may spy on you], 

Linux   - [https://www.raspberrypi.com/software/ Raspberry Imager Ubuntu], Suse Image / Multi writer, dd, 

Mac     - 


* Virtual Machine .ISO or CDs DVDs 

 The native iso images are currently not compatible with Ventoy, Yumi, MultiBootUSB, Easy2Boot E2B, or similar 

&lt;pre&gt;
617a905b1665128c5e05f94dcc48e7f1 *AROS-One-v1.3-64Bit-v11.zip
11c8a147fcad7ecf52ae3a43e1934b69 *ArosOne-DVD-v1.2-x86_64-v11.zip
f93053d3b9ccf304d7e6ac3389e1987b *ArosOne-DVD-v1.1-x86_64-v11.zip

86d808a40dc7be389a758799a9b4f595 *ArosOne-x86-v2.0-ISO-DVD.zip
f1fc8599ef6a39e5df394e0f41d55526 *AROS-One-x86-ISO-DVD-v1.6.zip
&lt;/pre&gt;


You can use a virtual emulator like VirtualBox, VMWare to mount the iso image which can then be used to boot and/or install to USB. 

No current software can write an AROS ISO to a Pendrive. The author of ‘Rufus’ (who used an Amiga 500 as a child) once tried, but when he saw the system composition, he said he was unable to do it.

The solution is to boot the ISO from a VM (WMware, VBox), then install the AROS build on the Pendrive, which will eventually become a Live Pendrive that can be booted on a PC.

The only precaution is that in some cases it is necessary to thoroughly clean the Pendrive of any partitions and remove any bootloader that is not AROS. The Pendrive must remain raw without any partitions.

You can clean the USB stick on a PC with a program that manages hard disks. You need to do a partition wipe. On some USB sticks, you can clean it with InstallAROS.
For some USB pendrives, please use a reputable partition editor to remove any and all partitions from a usb pendrive as HDToolbox cannot do this task sometimes with a wipe all option. 


Previously the only installation option was CD-RW or DVD-RW, since the whole system can be burnt onto a single disk and can be reused when the next version is released. Good branded discs like Taiyo Yuden (later JVC) or Verbatim should be used to reduce frustration later. The days for this media is gone but kept here for information 

Since nobody currently sells AROS on any other media, you will need access to a CD/DVD burner to create the installation disk yourself. After it is on a CD or DVD, then access and writing to USB pendrives becomes available (this should be viewed as an outdated or last resort alternative method now), as well as using good USB manufacturers like Sandisk, Kingston, etc. rather than some other no-names. 

Try burning it to a CD-RW or DVD-RW using your CD/DVD burning program (most burning software have a burn iso option). The ideal writing speed is 2x or 4x, higher speeds can give errors and problems.  Check the writing integrity of your CD or DVD if your software has an option to do so before going any further. 

Standalone portable usb cd dvd drives do not boot physical burnt discs, please use an internal ide sata drive instead. 


* SD-card
For [https://aros.sourceforge.io/nightly1.html ARM Pi Aros 64bit], copy the files onto a FAT32 formatted micro SD card. 


==Booting==

The LiveUSB, and in the past LiveCD LiveDVD, is designed to trial (test drive) various operating systems without having to install them to your working system. 

Since 2011, UEFI was introduced to replace the original PC BIOS which made booting media more confusing. Some changes in the UEFI/bios may be needed 

*go into the bios using esc, f2 or f? and disable the Security -&gt; Secure Boot and maybe apply option for Legacy IDE mode 
*you may have to press F9, F10 or F12 or p on boot up to present a device boot options like USB or CD/DVD 
*disable the Fast Boot config so it would recognize portable DVD-drive and changed the Boot-sequence

Secure boot was introduced by Microsoft and later consortium, control what operating systems work with Secure Boot via shims. 
For Aros, it is best to disable and save the turn off change to Secure Boot (if you dual boot with Windows this will cause issues with further Window boots) 

 For the best experience, it is advised to install to another SSD than the one Windows resides on. 

The grub part of the boot should be fully automatic, and you should see a multiple choice graphic card screen after 10 seconds for USB or 40 seconds CDs and DVDs. 
If boot does not occur within a minute, please reboot and choose the VGA boot option as it relays a message stream so you can see where the issue lies. 

After the grub graphics choice, AROS takes over the booting and any issues can arise here 

If possible please use a branded usb pen drive as most of the time when we get reports of &quot;crashes right after grub boot selection&quot; it is mostly due to the recorded pendrive as they are made, notoriously on a will it work / will it fail nature, every time it is used. 
&lt;pre&gt;
So one usb drive written may stop at a System halted. Reset the machine. 
Or another pendrive will show give errors Smart Filesystem request - Volume 'Aros Live Drive' (DU0: usbscsi.device unit 0) There was an error while accessing this volume: 
Or if a FAT32 partition present - FAT filesystem - Device USBSCSI0P1 has a read error on block xxxxxxxx - 
&lt;/pre&gt;
Sadly, no drive even branded are resistant or totally reliable, so the only solution is to try another pendrive, and possibly to repeat, until no errors. 
It will give an indication on how reliable the usb drive could be. 


=====Advice for various machines=====

Some of the stages involved and shown on the display in a typical AROS boot start up 

&lt;pre&gt;
[MultiLoader]
[ELF Loader]
[Boot]

[HPET] 
[Kernel:ACPI]
[Kernel:APIC-IA32]
[Kernel:SMP APIC]
[HiddStorage]

ACPI: ????
ACPI Error 
[ACPI]AcpiOs????
[BattClock] Got RTC century offset 0x32 from ACPI 

[PCI] Scanning bus ? 
[AHCI] Sata 
[Vesa]  only if vesa is chosen as graphics option 

[ATA] detect hd &amp; cd drives 
[ATA0?] ata-identity 
[packet] fat.handler be.handler, etc. 
[DOS] 
[Storage:Bus]
[Storage:Controller]

[MSS] USB setup
[ehciInit] Port ? maps to controller ? 

[I2C] 
[ATI]
[drm] nouveau 
[AROSTCP]   if you have network driver prefs set up to start when booting 


&lt;/pre&gt;

; If boot fails, please give us some indication (pictures or videos) where the boot stops and the message(s) on screen. 


AROS's native SATA/AHCI driver doesn't always work. If you get errors related to ahci.device, try disabling it. At your chosen boot entry in the GRUB menu, Press E, scroll down to the ahci.device entry, and add a # or ; at the start of that line or delete it with Ctrl-K. Then press Ctrl-X or F10 to boot. 

If your disk isn't accessible at all with this change, you might need to change the SATA controller to IDE legacy mode in the BIOS: however, making this change will likely cause problems booting Windows on the same machine (if it's already installed). To disable ahci.device permanently, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and remove the ahci.device line from all boot entries you intend to use.

SATA AHCI Timeout while waiting for device to complete operations with BIOS SATA entry set to AHCI mode stops at &quot;waiting for bootable media&quot; screen, changing BIOS SATA setting back to IDE mode may allow it to continue booting 

The ATA driver doesn't always work. If you get errors related to ata.device, try using the alternative in sys:devs/alt which is an older version.  Press E when your chosen boot entry is highlighted in the GRUB menu, scroll down to the ata.device entry, and change it to read &quot;module /Devs/Alt/ata.device&quot;. Then press Ctrl-X to boot. To make this change permanent, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and change the path to ata.device in all boot entries you intend to use.


Further options (removing the &quot; &quot;) to add to the GRUB menus to disable certain other components for debugging:

&lt;pre&gt;
Disable AHCI                        &quot;AHCI=disable&quot;
Disable NVME                        &quot;NVME=disable&quot;

Disable ATA:                        &quot;ATA=disable&quot;
Disable ATA:                        &quot;ATA=nopci,nolegacy&quot;
ATA safe mode:                      &quot;ATA=nodma,32bit&quot;
Disable IDE from SATA:              &quot;ATA=32bit,nosata2pata&quot;
VIA / SIS with cdrom read io errors &quot;ATA=nodma,nopoll&quot; 

noacpi                   all [PCI] devices to be invisible to AROS. disk drives work but network, sound won't 
acpi=strict              if there are issues with sound after boot 

noioapic                 alternative to no acpi 

Set AHCI                            &quot;AHCI=force150/force300/force600&quot;
Disable AHCI/SATA:       comment out with a # ; or remove ahci.device line with Ctrl-K

Disable USB:             comment out # ; or remove pciusb.device and poseidon.library lines with Ctrl-K
Disable native graphics: &quot;nomonitors&quot;
USB3                     &quot;USB=xhci&quot; 
&lt;/pre&gt; 

Other useful grub command line options - nomonitors, noacpi, vesahack, nopoll 

Press Ctrl and X together (or F10) to exit and boot with the new options. Just experiment with different variations until successful. Those working options will need to be reused with every reboot of AROS until you can edit the grub.cfg and make it permanent i.e. install to hard disk or USB. 


* If you use VESA mode, you can see the debug log if you add 'vesahack' to the command  line.  This  will set up split-screen mode. In the upper half you'll see AROS screen, in the bottom - debug log. 
* ACPI ie. PCI hardware - If  you  get  crashes  at  early boot, try adding 'NOACPI' to the command line 


If you're having boot issues and have a null modem cable and a spare pc, a boot log is always useful. Edit your grub line to include debug=serial but would try with an with sysdebug=all in the line later as it can cause issues booting on machines with sysdebug=all enabled (corrupts the cpu initialization). 

However, if you feel you have found a genuine bug/fault in AROS that needs attention, please use the [http://sourceforge.net/tracker/?atid=439463&amp;group_id=43586&amp;func=browse bug submission form] to record as much information about what happened, why, and what hardware etc. you have so that people may try to assist you 


For Virtual machines VMWare VirtualBox, etc., attach and press play to start the ISO image 

If booting hasn't worked then it could be down to Bios/UEFI settings  


=====nvme.device=====

 Since 2018, nvme drives are standard on most machines 

The requirement is that a PC can boot with legacy mode/BIOS at the moment - Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

 This is still in testing and its' use should not be on or near precious own data 


=====AHCI=====

 Starting taking over since 2011 on a lot of machines 

* Check that UEFI (replacement for PC BIOS) has options set to remove UEFI SecureBoot option and apply CSM 
* SATA drive is set for Legacy or a mixture AHCI/IDE and not AHCI 


 AHCI sata can be very difficult to get working

Most Windows installs are already set to AHCI sata, changing this to a legacy IDE mode setting can help but please check if Windows will still boot. Some hardware like Lenovo laptops do not always like being set in legacy mode so only use as a last resort and aware of issues that can be caused. 

Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

With a 16C/32T chip machine, disable SMT and it should boot. 


=====ata.device for old BIOS's =====

 Pre 2010 this was the de facto standard method of providing settings to the computer at a lower level 

Some adjustments to the BIOS setup options are necessary (usually by pressing a key like DEL, F1, F2, F12 or ESC, p on the very early boot up of the computer). 

*Adjust booting options like moving USB hdd, CDROM higher as it is quite often disabled or placed lower by default, i.e. USB hdd, CD/DVD are placed at the top above the hard drive. Try looking here [http://www.windowsreinstall.com/articles/bios/ Windows] or [http://www.hiren.info/pages/bios-boot-cdrom Bios] or [http://www.wikihow.com/Set-Bios-to-Boot-from-a-CD-ROM Boot] or web search &quot;BIOS BOOT CDROM&quot;

* At the '''SAME''' time, check if the SATA/AHCI option is set to Emulate or IDE Legacy, though this can have '''issues''' with any OS already on the hard disk. If in doubt, do nothing and seek advice. 

* check that under BIOS settings you '''DO NOT''' have plug&amp;play OS selected as Aros at this point is unable to route interrupts on its own and needs the BIOS to do that. 

'''Save''' options changed at the end. 

PCITool can show if the motherboard chipset is in IDE mode. 
Class = 0x01 means STORAGE, Subclass = 0x01 means IDE. Also ProductID 0x3a20 resolves to non-AHCI mode in Intel ICH10 documentation.


==Installing==

We have a separate section [https://en.wikibooks.org/wiki/Aros/Platforms/x86_installing here]

We have a specific section for each CPU platform under the Specific platforms in the NavBar navigation bar on the right hand side menu 

error code (-6) when using the ahci.device (has writing to disk problem but not reading) is enabled. change this line in your grub and reboot 

&lt;pre&gt;
#module /Devs/ahci.device      &lt;&lt; disable
module /Devs/Alt/ata.device    &lt;&lt; add this line instead
&lt;/pre&gt;


==File structure overview==

AROS' directory structure is mostly identical to AmigaOS directory structure, with some additions.

AROS: or SYS: also known as DH0: (i.e. the drive partition with AROS system) has the following simplified list of the main drawers (Amigas term for directories/folders). 


{| class=&quot;wikitable&quot;
|boot:
| grub bootloader 
|----
|C:
| small apps, where AROS looks first for applications/games but will look at Tools, System afterwards
|----
|Classes:
| .class 
|----
|Devs:
| .device .resource and in their own drawers (folders) .audio, .hidd, network, graphics 
|----
|L:
| where .handler files go 
|----
|Libs:
| where .library files go 
|----
|Prefs:
| applications that adjust or setup AROS functions and capabilities 
|----
|S:
| startup scripts (for the aros boot process '''not''' grub) are stored here
|----
|Storage:
| place to keep old or alternative device drivers
|----
|System:
| applications associated with AROS operating system
|----
|Tools:
| extra applications
|----
|Utilities:
| extra applications
|----
|WBStartup:
| copy applications here to autostart with needed icons, drawers, data etc
|----
|}

See [[Aros/User/DOS#Drives.2C_Files.2C_Assigns.2C_Directories|DOS manual: Drives, Files, Assigns, Directories]]


=== Filesystem ===

Whilst the kernel is the heart, the filesystem is the blood of the system they are split into two categories (only a few are supported) 
&lt;pre&gt;
Journalling     - SFS PFS3 but also NTFS ZFS XFS ext4 
Non-journaling  - FFS FAT32(VFAT) but also exFAT BtrFS ext2  
&lt;/pre&gt;

Filesystem options for AROS to install 
* SFS default 
* Professional File System PFS3 [http://eab.abime.net/showthread.php?t=52234&amp;highlight=pfs3+free&amp;page=13 only on motorola 68k at the moment] 
* FFS very old now but left in for legacy usage 

Other [https://archives.arosworld.org/index.php?function=browse&amp;cat=driver/filesystem filesystems] for storage purposes 
* FAT32 favorite as most OSs support 
* NTFS (can lock AROS) 
* exFAT 

The only filesystems that really NEED defragging (i.e. disk tidy up) are from Microsoft(TM) - exFAT/VFAT/NTFS
*SFS tries to do exactly the same thing, but in certain cases it doesn't do as well as PFS. But you can defrag SFS 
*PFS *minimises* the amount of fragmentation, but does not automatically defrags as it saves files to the drive 

The setup of the below filesystems is usually done by the distro maintainer but if not....
&lt;pre&gt;
Copy L/exfat-handler L:

DOSDriver or Mountlist entry for an exFAT partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = exfat-handler
DosType        = 0x46415458
&lt;/pre&gt;

&lt;pre&gt;
Copy L/ntfs3g-handler L:

DOSDriver or Mountlist entry for an NTFS partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = ntfs3g-handler
DosType        = 0x4e544653

Also to make a read-only mount you can set:

Control        = ro
&lt;/pre&gt;


The Smart File System (SFS) is a journaling filesystem used on Amiga computers and AmigaOS-derived operating systems. It is designed for performance, scalability and integrity, offering improvements over standard Amiga filesystems as well as some special or unique features.  

SFS is written in C and was originally created and released as freeware in 1998 by John Hendrikx. After the original author left the Amiga scene in 2000, the source code to SFS was released and its development continued by Ralph Schmidt in MorphOS. 

Its development has now forked; as well as the original Amiga version, there are now versions for MorphOS, AROS, AmigaOS 3, and a version for AmigaOS 4, which have different feature sets but remain compatible to each other.  Versions for AROS, AmigaOS and MorphOS are based on different branches.  

In addition, there is a driver for Linux to read Amiga SFS volumes, GRUB natively supports it and there are free drivers to use it from UEFI.  The Linux version is [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ independent code].  

SFS (Smart File System) partially defragments itself while the filesystem is in use. The defragmentation process is almost completely stateless 

AROS SFS version has a 120GB partition size limit on hard disks and DVDs current 4gig size limit. 
The sources for the MorphOS 64-bit version of SFS were available but no porting to AROS has happened so far due to endian issues, etc. 

SFS Tools 
* GUI - arSFSDoctor, 
* CLI - sfscheck , [http://www.portacall.org/ sfsundelete], sfsformat, setcache hits a usability ceiling around the 10GB / 100,000 file mark, 

 sfscheck dh0: seek purge fraglist defragment

If there are two simultaneous file writes in progress and you reboot machine (or it locks up or crashes) you may end up with a corrupted filesystem. Although arSFSDoctor may help, you might have to copy the files to another partition, format the partition with the errors on and copy the files back. 


PFS / SFS are way more advanced and much much faster than the FFS. FFS is supported for legacy reasons only. 
The Professional File System (PFS) is a filesystem originally developed commercially for the Amiga and now distributed on Aminet with a 4-clause BSD license. It is a compatible successor of AmiFileSafe (AFS), with an emphasis on added reliability and speed compared to standard Amiga filesystems.  It also features multi-user abilities like the older MuFS. 

PFS has so many advantages including the important things, speed, the ability to recover all deleted files even simply same name by typing the command &quot;. Deldir&quot; convenient if done in Directory Opus, virtually deleted files are copied normally as if they had never been deleted, other convenience is to not ever invalidate the filesystem, just put it on top of the startup-sequence command &quot;diskvalid&quot;, which automatically corrects any irregularities in the system startup; PFS also provides a device for floppy which makes them very fast and takes advantage of the full capacity of the floppy including the area dedicated to the bootloader.

The device is split into two main areas. At the beginning of the device is the metadata section, which consists of a root block, and a generic array of blocks that can be allocated to store metadata. The rest of the device is another contiguous generic array of blocks that can be allocated to store data. The metadata section usually uses a few percent of the device, depending on the size of the device.

The metadata is stored as a tree of single blocks in the metadata section. The entire directory structure is recorded in the metadata, so the data section purely contains data from files. The metadata describes the location of data in files with extents of blocks, which makes the metadata quite compact.   

When a metadata update occurs, the system looks at the block containing the metadata to be changed, and copies it to a newly allocated block from the metadata section, with the change made, then it recursively changes the metadata in the block that points to that block in the same way. This way, eventually the root block needs to be changed, which causes the atomic metadata update.   

The filesystem is reasonably good at keeping files unfragmented, although there is a defragmentation tool available which will work on an online filesystem ie whilst being used. 

It was the first filesystem to introduce the concept of the Recycle Bin natively at filesystem-level to the Amiga, holding the last few deleted files in a hidden directory on the disk root.  

PFS version 5.3 was developed in C and a small portion of assembly code by Michiel Pelt.  There are endian issues to be overcome and adapting the small amount of m68k to C before use on intel based machines, etc.  


Autoupdate of files in a directory is already implemented in Wanderer, but not all file systems handle dos.library/StartNotify() in its full extent. It seems to work correctly in Ram Disk (thanks to AmberRAM handler), and it also works on SFS formatted devices. Other file systems might not yet have it implemented correctly though. 

The PC equivalent of the Amiga's RDB is the master boot record (MBR).


===Installing Applications===

The typical means to install applications under AROS/AmigaOS involves simply copying/extracting the archive (.zip .lha .rar .tar.gz) file containing the applications files to your own desired location i.e. drawer/folder. Once extracted, launching it by double clicking on an icon (recommended) or using the shell (alternative). Generally, this is on a separate partition from your AROS system files, however in reality it can be any location - including RAM: if you don't want it staying around too long especially when you switch off. 

At some time in the future it may be desirable for AROS to have a package-manager like subsystem able to retrieve information online about packages available for AROS and whether they update anything you currently have installed, however at the moment no such ability exists.


===User Data files===

AmigaOS has no notion of a default location to store user data files, and presently neither does AROS - though it may be desirable at some time to provide a common start location.

Some people, have extra small FAT32 partition(s) using HDToolbox, and not Qparted, to store data especially if a reinstall is ever needed. And then setup the usual Sys: (DH0:) and maybe Work: (DH1:) / Live USB (DU0:) and maybe Briefcase (DU1:) partitions. 


===User Environment configuration files===

AmigaOS/AROS stores persistent system configuration data in directory assigned to ENVARC:.  This, by default, points to SYS:Prefs/EnvArc.

During boot a copy is made to another assign, ENV:, which is for runtime usage.  Changes to the files here will not survive a reboot.

Setting the env variables is generally done by applications themselves, or when necessary by the user using the SetEnv command. SetEnv has a SAVE switch to force the persistent copy in ENVARC: to be written also for when you are sure the change should be permanent.

Under the standard installation of AmigaOS style OSs, ENVARC: is copied to ENV: upon startup, which, if you have a hard drive installation, is in RAM:, hence, ENV: ends up being RAM:Env.

ENVARC: is the Environment Archive, which is the permanent copy of ENV:, which is the Environment.  It's roughly like the Registry in Windoze. 

Most programs do (and all should) store their settings in ENVARC: somewhere, and load them from ENV:.  The effect of this can be seen in the Preference editors.  If you Save your preferences, they go in ENVARC: and ENV:.  If you click Use, they only go in ENV:.  If you reboot, normally, anything saved to ENV: is lost, and is replaced with a copy of what is in ENVARC:.

you can set the default public screen for any tool started from a cli with the PUBSCREEN variable. So open the pubscreen, set PUBSCREEN to the name and start newcli for example, then the new cli window (and all following windows opened from that window) will appear on that public screen.


===Drivers===

For certain hardware, e.g audio, networking and , there is no auto setup. Just like the original Amiga OS. 
For audio, use AHI in the Prefs folder to set Music and at least Unit 0 with the appropriate driver and press Save. For ethernet and wifi, please use SYS:Prefs/Network 

All hardware support is placed in the Devs drawer (folder/directory). The network drivers &lt;something.device&gt; go in the Networks sub-drawer. Audio drivers &lt;something.audio&gt; are put in the AHI sub-drawer. Graphics drivers &lt;something.hidd&gt; are put in the Drivers sub-drawer. 


==Configuring==

AROS has mainly decided on a MUI-like requester&amp;menu clone called Zune so changing the background, icons, font, menus can be done with SYS:Prefs/Zune 

AROS has several desktop GUI front ends like 
* DOpus5 Magellan II, Wanderer and Scalos (medium) 
* AROS Workbench, Workbook (smaller) 

File / Directory managers like Dopus4, MCAmiga, 

App Launch Shortcuts like FKey, BoingIconBar, right mouse click on magellan, wanderer desktop, Amistart, etc. 

General usability decisions - Prefs/IControl, Prefs/Locale, Prefs/Input, Prefs/Fonts, 


Select an icon with left mouse button and then right click the mouse button and selecting Icon -&gt; Information gains access to the tooltypes tab where information can be edited 

CLI in icon's tooltypes means 'run it as if it was run from shell'
If, on the other hand, the WB parameter (or no parameter) is present in Tooltypes, Wanderer will execute the binary and, if provided, the options included in Tooltypes. 

WBxCLI is very useful for adding options to DOS Commands.

Important: AROS has a different way of managing icons. If you have an executable file, you will never be able to add a project icon. AROS will automatically recognise that it is an executable file and will transform the icon into a tool icon.


Icons are typically now .png pictures renamed as .info e.g. so Office application name would have a Office.png renamed as Office.info or MyApp.png as MyApp.info, etc.  

Leave Out menu option to leave app icon on desktop 

To select multiple icons and save their positions, click on the first icon and after while you hold the Shift key down select further icons and don't release it before SnapShot is finished.  You can also select a whole group of icons by pressing the LMB at the top left of the icons and while keeping the LMB down moving the power towards the bottom right. A expanding bounding box will appear and all the icons within it will be selected.  

Clean Up menu option (right mouse button -&gt; Icons) rearranges icons in a drawer or disk window into a neater condition. To use, open the window to rearrange and select Clean Up. To keep the icons in the new positions, select all the icons (shift key or mouse selection) and select 'Snapshot' and then Window and then again with All.  

In DOpus5, Scalos, wanderer, most files have an icon file associated with it. To change the default tool, select Icon menu, Information, and change the default tool string. For example, you could use Multiview, Editor and so on for most text, graphics and some sound files as long as the appropriate Datatype classes are installed. For scripts, set the tool to C:IconX 


We have new Icon edit tools in progress but if you need to...
 C:Join Image1.png Image2.png TO MyFile.info
is enough to make a dual state icon from two png images. You can then use Wanderer's menu Icon/Information on it to edit its fields and tooltypes.

[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/icon AISS toolbar images] unpack unarc them into RAM: and copy Images directory to SYS:Prefs/Presets/  AISS icons are looked for in PROGDIR:, PROGDIR:Images, SYS:Prefs/Presets/Images and then in TBImages: according to Open Amiga guidelines.  

there is Demos/iconscale which could be launched from S:User-Startup with two arguments, telling it the horizontal and vertical size. IE something like 
 Demos/iconscale 40 40
It will shrink icons... not sure if it will be very nice though. it doesn't work for the icons on the main desktop. 

there is an option to scale an icon to a bounding box afair, try iconsize followed by two numbers, like:
 iconsize 32 32

Is there any way in AROS to change an icon type from Project to Tool or vice versa?
Either the SIT option of [ ProcessIcon], or the TYPE option of HandleInfo (not sure if this one works at all, please test with care).
 processicon sys:pathoftheicon SIT=Project 

SIT Set type of ICON. Allowed types are: &quot;Disk&quot;, &quot;Drawer&quot;, &quot;Tool&quot;,  &quot;Project&quot;, &quot;Garbage&quot;, &quot;Device&quot;, &quot;Kick&quot; and &quot;AppIcon&quot;.

Btw, are your icons, the #?.info files, writable, is the W flag set ?


'''Decoration''' is Aros' way to provides a way to hide the old Workbench 3.1 style of windows and screens. In Prefs/Appearance some decorative theming elements need work 

Themes - SYS:Prefs -&gt; Appearance 
The default content of Prefs/Env-Archive/SYS/themes.var should be &quot;themes:ice&quot; but can be changed via the Appearance prefs, please do NOT click the Use button. Its useless. As you know, it will ask for the theme volume. Just pick the theme you want, click on Save, then reboot. 

* Decoration is on. Any time trying to change theme, you get: &quot;Please insert volume Theme: in any drive&quot;? 
You could check if you find SYS:System/Themes or if it is missing. Then you could open startup-sequence which you can find in drawer &quot;S&quot;. There should be a line: 
 Assign THEMES: SYS:SYSTEM/THEMES &gt;Nil: 
This does the trick. 
Open a shell and run: 
 Assign THEMES: SYS:SYSTEM/THEMES 
Than start the Theme prefs again... this should work 

* The theme is the only thing that could slow the system a bit, but it's not that performance impacting on most uses, and you can switch it off completely. Remove C:Decoration from the bottom of the file sys:s/startup-sequence. 

In each theme directory is 
*Env-Archive -&gt; Zune -&gt; global.prefs
*images -&gt; Gadgets -&gt; 20x20 pngs for Down etc 
*menu -AmigaKey - Background - Checkmark - SubMenu and config
*system - Arrowdown, Arrowleft, Arrowright, Arrowup, etc 


There is an [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/theme ALua/Zulu script] built for faster Wanderer skin management. You can modify config files, install new (wdz format/zipped skin files) and delete skins via the Theme Manager. This has not been updated in a long time and may not work. 


Exchange controls Commodities and can be opened with alt, ctrl, h 

Certain features are added if from Tools/Commodities like Blanker screensaver, ClickToFront and DepthMenu with .info icons are selected and dragged to /WBStartup folder 

Most apps can be autostarted by copying into SYS:WBStartup directory folder 
e.g. WeatherBar.zip can be downloaded, unzip and the contents of the zip copied to wbstartup folder 
 ClicktoFront and .info to SYS:WBStartup so always be activated when turning on the computer 

or add a text line to user-startup is SYS:S (scripts version of wbstartup) 

e.g. standard Amiga / AROS does not allow clicking of background windows to come to the front to make it easy to get to the window you need but it has the ability if these apps are copied again to WBStartUp or are added to SYS:S/user-startup script 

 run QUIET sys:Tools/Commodities/ClickToFront &gt;Nil: 
 run QUIET sys:Tools/Commodities/DepthMenu &gt;Nil: 
 run QUIET sys:Tools/Commodities/Blanker seconds=300 &gt;Nil: 

*AltKeyQ uses left Alt key to add strange letters 
*AutoPoint 
*Blanker screensaver 
*ClickToFront allows windows to be easily brought to the front 
*DepthMenu adds menu to select window easily 
*NoCapsKey
*Opaque 
*FKey - Although there are heaps of docks, menus and other launcher programs on the Amiga like OSs, FKey has got to be one of the quickest once learnt ways to launch programs, and it comes with the OS. In SYS:Tools/Commodities, the FKey commodity (Ctrl Alt F) allows you to make actions assigned to some combinations of keys 

&lt;pre&gt;
ALT TAB       Cycle Windows
              Cycle Screens
              Enlarge Window
              Shrink Window
              Toggle Window Size
              Insert Text
              Run Program
              Run Arexx Script
&lt;/pre&gt;

e.g.
&lt;pre&gt;
LAmiga F1               = Avail Flush
LAmiga F2               = Open Prefs
LAmiga F3               = Finder
Alt Tab                 = Cycle Windows
LAmiga Tab or M         = Cycle Screens
Alt Up arrow            = Enlarge Window 
Alt Down arrow          = Shrink Window
Alt Home                = Toggle Window Size 
                        = Insert Text             
LAmiga e                = Run Program             
                        = Run Arexx Script        
&lt;/pre&gt;

If your FKey GUI pops up when you start your Workbench up and you don't want it to, click once on the icon, go to the Icons-Information in the menu and make sure it has the tooltype set &quot;CX_POPUP=NO&quot;. 

Now let's launch it and assign the locale switching. After you double-click on FKey icon, launch the Exchange, choose the FKey from list and click the Show button. This will invoke the FKey window. You can see the ALT TAB in list assigned to window switching. Now enter the first key combination, say, ALT Z and go to the right panel. Choose Launch the program from pulldown menu and enter SYS:Prefs/Input as an argument. Append the USE switch and english preset name to the string as shown:

SYS:Prefs/Input USE SYS:Prefs/Presets/english

Click on the New Button to add the another combination. Now set the combination for your locale as shown above, replacing English name with your preset name. Click New button again and then Save Settings. Now you can use defined combinations to switch the layouts.


There is a system wide ARexx script capability (based on regina) that can manage many file manipulation task(s) but this would work only with those program that support [https://en.wikibooks.org/wiki/Aros/Developer/Docs/Rexx ARexx] like 

*Desktop - DOpus5, Scalos 
*Dock - FKey, 
*Files - Multiview, DOpus4, 
*Internet Apps - Odyssey, WookieChat, 
*General Apps - 


the shell can be modified with escape strings but not needed in most cases 


 Common Keyboard Shortcuts

&lt;pre&gt;
RAlt Right Alt Key 
LAlt Left Alt Key 
RWinKey Right Windows Key 
LWinKey Left Windows Key 
RAmiga Right Amiga Key (if one)
LAmiga Left Amiga Key (if one)
&lt;/pre&gt;

;Bootup Options 
:Spacebar during boot, enters the bootmenu which allows a boot without startup sequence, etc  

;Left Click 
:LAmiga = LWinKey = F11 

;Right Click 
:RAmiga = Help = F12 

;Mark 
:RAmiga and B 

;Cut 
:RAmiga and X 

;Copy 
:RAmiga and C 

;Paste 
:RAmiga and V 

;Search 
:RAmiga and S 

;Mouse Movement 
LAmiga and together with arrow keys - shift as well at the same time as well to move faster 

;Mouse Selection 
LAmiga and LAlt to select 

;Screen Switching 
LAmiga and M or N 

;HELP key 
Can sometimes be mapped to F11 but can be changed via FKey 


ComKeyRemapper or AmigaKeyremapper could swap RAmiga to another key press 


===DOpus 5 Directory Opus Magellan II===

Dopus 5.x is a whole desktop replacement on the Amiga Workbench (Desktop) 

DirectoryOpus app will assign DOpus5: to it's PROGDIR: automatically but if not add the below (edit SYS:System to suit where Dopus5 was installed) to your startup-sequence 

&lt;pre&gt;
Assign DOpus5: SYS:System/DOpus5 
DOpus5:DirectoryOpus 
;DOpus5:C/LoadDB
&lt;/pre&gt;

Left mouse button clicked twice on the desktop background brings up the Device List window. 
Green strip notifies SRCE (source) and if another is open it will be red for DEST (destination). clicking on the red strip changes to green 

Word list of actions with a left mouse click on the DOWN Arrow and directory stuff with &lt; button which mirrors the icons at the top of each lister 

single-key hotkeys? exactly the same as in dopus4, edit your functions (button bank, toolbar, menus etc.) and under the flags gadget is a key gadget, just click in it and press the key you want to use.

As for the extra text field... try turning off Extended lister key selection in environment / miscellaneous.

Shift and click on the icon - runs the icon 


DOpus5 Magellan 2 Directory folder drawer structure 
&lt;pre&gt;
ARexx       - Arexx scripts .rexx and .dopus5 to perform tasks 
Buttons     - 
Commands    - 
Desktop     - 
Environment - two environment files bundled:
 default gets loaded if you run DOpus as a normal app
 workbench gets loaded if you run DOpus as a WB Replacement (with LoadDB on startup)
Filetypes   - 
Groups      - 
Icons       - 
Images      - 
Modules     - compiled tasks 
Settings    - 
Sounds      - 
Themes      - 
WBStartup   - Use this if standard SYS:WBStartup gives cannot wait error messages 
&lt;/pre&gt;


Settings -&gt; Environment -&gt; Display -&gt; Workbench (Use) 


*Settings -&gt; Clock (add to title bar as well as the date) 

*Toolbar  -&gt; Editor (Right Win Key together with 1) for Copy, Move, Delete, etc above the Device List 
*Menu     -&gt;  (Right Win Key together with 2) 
*Buttons  -&gt; Editor (Right Win Key together with 3) 

*Settings         -&gt; Environment (Right Win key together with 4) for Backgrounds, etc 
*File Types       -&gt;  (Right Win key together with 5)
*User Menus       -&gt;  (Right Win key together with 6)
*Hotkeys          -&gt; Setup for quick shortcut keypresses (Right Win Key together with 7) 
*Scripts          -&gt;  (Right Win key together with 8)
*Icon Positioning -&gt;   (Right Win key together with 9)


Each Dopus5 theme are stored in a separate directory, named appropriately, which contains further sub directories 

* Font (amiga bitmap fonts)
* Screens (jpg or any picture supported by datatypes but not animations) 
* Sounds (wav but not iff 8svx ) 
* Icons (png newicons glowicons ) 
* Patterns (iff jpg png ) 


Just use wildcards in background filenames and you get a different picture every reboot 

For example, configure in Environment -&gt; Backgrounds -&gt; Desktop something like this:
&lt;pre&gt;
Work:Pictures/Backgrounds/#?
...or 
Work:Pictures/back#?.iff
...etc...
&lt;/pre&gt;


[https://aminet.net/util/dopus arcdir and themes]  


If you want to change the backdrop pic after a period of time, paste below into a text file called dopusrandbg.rexx and place in DOPus5:ARexx 

&lt;pre&gt;
/* Changes DOpus background image forever

   Start with:
   Run &gt;NIL: RX dopusrandbg.rexx 
*/

if ~show(&quot;L&quot;, &quot;rexxsupport.library&quot;) then do
	if ~addlib(&quot;rexxsupport.library&quot;, 0, -30,0) then exit 10
end

/* Configure these two lines for your needs: */
minutes=1
picpath=&quot;Work:Pics/#?.iff&quot;

address DOPUS.1

do forever
	call delay 3000*minutes
	dopus set background '&quot;'picpath'&quot;' desktop center custom
	dopus refresh background custom
end
&lt;/pre&gt;


If you don't want to use/open rexxsupport.library just for DELAY() then use the DOS Wait command

&lt;pre&gt;
/* random diropus backdrop changer */
/* by paul trauth, 1999 */
/* to do: non-repeatable randomness? */

options results

parse arg path

address DOPUS.1

/* get current backdrop pattern so it actually changes */

dopus query background desktop custom
currentpatt=result
lastslash=lastpos('/',currentpatt)
currentpatt=substr(currentpatt,lastslash+1,(pos('&quot;',currentpatt,2)-lastslash-1))

dir=showdir(path,'FILE','/')
num=0
do while dir~=''
    where=pos('/',dir)
    if where&gt;0 then do
        file=left(dir,where-1)
        dir=right(dir,length(dir)-where)
    end
    else do
        file=dir
        dir=''
    end

    if left(file,1) ~='.' &amp; file~=currentpatt then
        do
            pics.num=file
            num=num+1
        end
end

which=random(0,num-1,time(s))
newbg='&quot;'||path||'/'||pics.which||'&quot;'

dopus set background newbg desktop tile precision exact
dopus set background on
dopus refresh background
&lt;/pre&gt;


Clock format commands available are defined by locale. They are:
&lt;pre&gt;
 %a - abbreviated weekday name
 %A - weekday name
 %b - abbreviated month name
 %B - month name
 %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
 %d - day number with leading 0s
 %D - same as &quot;%m/%d/%y&quot;
 %e - day number with leading spaces
 %h - abbreviated month name
 %H - hour using 24-hour style with leading 0s
 %I - hour using 12-hour style with leading 0s
 %j - julian date
 %m - month number with leading 0s
 %M - the number of minutes with leading 0s
 %p - AM or PM strings
 %q - hour using 24-hour style
 %Q - hour using 12-hour style
 %r - same as &quot;%I:%M:%S %p&quot;
 %R - same as &quot;%H:%M&quot;
 %S - number of seconds with leadings 0s
 %T - same as &quot;%H:%M:%S&quot;
 %U - week number, taking Sunday as first day of week
 %w - weekday number
 %W - week number, taking Monday as first day of week
 %x - same as &quot;%m/%d/%y&quot;
 %X - same as &quot;%H:%M:%S&quot;
 %y - year using two digits with leading 0s
 %Y - year using four digits with leading 0s
&lt;/pre&gt;
like %a %d-%b-%y %H:%M or 


A WB ARexx interface, you could enter a cli command as a menu item to open a WB drawer like this...
 RX &quot;address WORKBENCH;WINDOW 'device:drawer' OPEN&quot;
Where device:drawer is replaced by the path of the drawer to open. 

The ARexx script would be capable to manage such a task but this would work only with those program that support ARexx 

&lt;pre&gt;
dopus addappicon
dopus addtrap
dopus back
dopus checkdesktop
dopus clear
dopus command
dopus desktoppopup
dopus error
dopus front
dopus getdesktop
dopus getfiletype
dopus getstring
dopus matchdesktop
dopus progress
dopus query background, font, palette, pens
dopus read
dopus refresh all, background, icons, lister
dopus remappicon
dopus remtrap
dopus request
dopus script
dopus screen
dopus send
dopus set background, font, palette, pens
dopus setappicon
dopus version
&lt;/pre&gt;

&lt;pre&gt;
lister add
lister addstem
lister copy
lister clear value
lister clearcaches
lister close
lister empty
lister findcache
lister getstring
lister iconify
lister new
lister query active all, dest source
lister query abort, busy, case, dirs, display, entries, entry, files, flags, handler, header, hide 
lister query label, lock, mode, namelength, numdirs, numentries, numfiles, numseldirs, numselfiles
lister query path, proc, position, seldirs, selentries, selfiles, separate, show, sort, 
lister query title, toolbar, value, visible, window
lister read
lister refresh
lister reload
lister remove
lister request
lister set busy, case, dest, display, field, flags, handler, header, hide, label, lock, mode
lister set namelength, newprogress, off, path, position, progress, separate, show, sort, source
lister set title, toolbar, value, variable
lister select
lister wait
&lt;/pre&gt;

The '''command''' allows you to call internal DOpus commands from an ARexx script

&lt;pre&gt;
command all
command wait copy
command read s:startup-sequence
command source 12345 makedir name noicon
&lt;/pre&gt;


*SFTP secure encrypted comms over internet using libssh2 and zlib (different protocol to the two below) on port 22 
*FTPS secured with https like security on port 21 
*FTP not secure and unencrypted protocol over internet on port 21 (should not be used today on the internet but for your own server) 


===Wanderer ===


Wanderer prefs in the prefs drawer - Appearance tab and Workbench icon allows backgrounds (wallpapers) icon text sizes, colors, etc but cannot use #? or *.* in the backgrounds file entry to randomly choose pictures - [https://developers.google.com/speed/webp/docs/riff_container webp riff container] issues with this format but Multiview has none. 

Enable the bar, you need to edit the text file ‘statusbar.prefs’. The change is simple: just change “False” to ‘True’.

Prefs/Env-Archive/SYS/Wanderer/statusbar.prefs 


===Scalos===

[https://web.archive.org/web/20180922220139/http://scalos.noname.fr/ Scalos] is not an OS replacement, it's a Workbench replacement. It replaces the desktop and graphical file management components. 

Scalos is 100% Workbench replacement with most functions working like the original Workbench ones. Undo and Redo available for most window and icon operations. Fully multitasking so every window has its own task. While loading icons, any window function (e.g. Drag&amp;Drop) is available. 

24bit color support with window patterns - Unlimited and easily configurable via tooltypes. Optimised backgroundpatterns routine so patterns can be tiled, centred or even scaled to fit into the windows. Live updating window scrolling - Supports middle mouse button panning and drawer (folder) windows can be iconified on the desktop. 

Icon imagetypes with all types are supported such as backfill or complement. Configurable surrounding iconborder. Icon support also visually highlights files which are soft-links in the file system. Icon dragging is more stable and far less flickery on graphics cards. Whilst dragging, icons are displayed with text and they can become transparent over anything where they can be dropped. 

Single-window lasso mode, with scrolling window contents invoked by dragging mouse with configurable qualifier key. Text icon lasso selection used to ignore &quot;Name column selects text icons&quot; flag. Support for backfilled thumbnail icons, with selectable color and transparency. Added option to always generate square thumbnail icons with preview icons for images - Thumbnails can be permanently saved in icons. 

Supports PNG icons with alpha channel and real transparency and displays OS3.5 GlowIcons and are all scalable. Iconborders with variations (normal, shadowed, outlined). 

Completely configurable, filetype-specific user-definable popup menus and tooltips. Plugin system to exchange or add features and can enhance the Workbench and make it more configurable. 

Filetype plugins to display filetype-specific information. - Currently, EXIF information viewer for JPEG images is included. Plugin included for 100% support of OS3.9 Workbench features. Plugin included for AREXX API compatible to OS3.9 Workbench. 

Online update with updater.module


Scalos works also as a Workbench replacement. In this case the 'emulation mode' has to be set by using Scalos' own version of LoadWB and offers 
* Scalos uses the Workbench Screen for its windows instead opening a new one 
* AppIcon, AppMenuItem, AppWindow functions are redirected to Scalos
* all Programs placed in &quot;WBStartup&quot; should start 
* The Screen will be reopened in case of changes in ScreenMode and Palette settings


&lt;pre&gt;
v1.0 (V39.201) - November 1999
v1.1 (V39.212) - December 1999
v1.2b (39.220) - June 6, 2000
v1.2d (39.222) - 2000 (latest public beta executable)
v1.3 (40.7) (beta) - August 2, 2001
v1.3 (40.22) - September 25, 2002
v1.4 (40.32) (beta) March 31, 2005
v1.6 (41.4) - March 27, 2007
v1.7 (41.5) - August 12, 2007
v1.8 (41.6) - March 12, 2009
v1.9 (41.7) (beta) - March 15, 2010
v1.9 (41.8) (RC1) - August 25, 2012 open source 
v1.9.2 (41.10) Deadwoods' AROS late 2022 32bit and 64bit build unifying the code base of ` for AROS x86 ABIv0, AROS x86_64 ABIv11 and AROS m68k  
&lt;/pre&gt;


Distros may have Scalos files under SYS:System/Scalos or Extras:Scalos. Known [https://github.com/deadwood2/AROS/issues/75 bug list], 


 Certain files like Menu13.prefs, Palette13.prefs, Pattern.prefs and scalos.prefs need to be in SYS:Prefs/Env-Archive/Scalos they can be found in Scalos:Storage/envarc and country drawer 

or run the &quot;Scalos Menu&quot; preferences program. Note if already setup with sub-menu entries and then re-save your menu prefs as it will now generate a new/overwrite prefs file called &quot;Menu13.prefs&quot; in &quot;envarc:scalos/&quot;. The same is also required for the new Palette prefs update, click 'Save' and a &quot;Palette13.prefs&quot; file will be saved in to &quot;envarc:scalos/&quot; directory. 


&lt;pre&gt;
ASSIGN Scalos:             SYS:xxx/xxx DEFER   
ASSIGN Libs:               Scalos:Libs add    
;ASSIGN SYS:Devs/Datatypes  Scalos:Devs/Datatypes   add  
Assign Theme:              Scalos:Themes/Default_Theme add 
Assign Locale:             Scalos:Locale add 

Protect Scalos:Tools/browse.script s add quiet 
Protect Scalos:Tools/OpenShell s add quiet 
Protect Scalos:Tools/run.script s add quiet 

run Scalos:Tools/LoadWB 
;Scalos:Scalos
&lt;/pre&gt;

Add the above to SYS:S/startup-sequence or SYS:S/user-startup '''before any Wanderer entries''' 


In the prefs drawer (folder) is the big prefs app Scalos_Prefs which covers these user setup areas 
&lt;pre&gt;
About Scalos
Paths               - should be preset 
Startup             - WBStartup drawer contents should auto run on each startup 
Desktop             - edit titlebar, icon layout and in misc, auto leave-out (drag icon to desktop) 
Icons               - 
Drag and Drop       - 
Windows             -
Text Windows        -   in misc, drawer sorting at start of listing if needed 
TrueType Fonts      - use Truetype fonts rather than system ones 
Miscellaneous       - 

Plugins             - after adding oop/title_clock.plugin %ti %da does not work, maybe needs ASCII .prefs added 
Modules             - ??
Menu                - setup for MainMenu and PopupsMenu with New Menu, RE Name, Key: shortcut, Command Properties 
FileTypes           - already added def_Project icons and def_Disk (hdd sdd cd dvd etc) support 
PopupMenu           - tweak how popups appear 
Pattern             - Wallpaper backgrounds with Type DE, each pattern in the list can be edited, Save as Pattern.pre 
Palette             - change the color of things , Save as Palette.pre 
&lt;/pre&gt;


Scalos_Prefs - Pattern - Minimum options to be changed are 
*DE Desktop/Background 
*SC Screen 
*TW Window/TextBackground ie Text listing showing if icon type not recognised 
*IW Window/Background ie Icons showing 

 Workflow - In &quot;Pattern List&quot; tab, select New - choose a picture, highlight in list, click in number box under New button and slide to another number, click on &quot;Defaults&quot; tab and adjust Pattern numbers slider to choose right picture for each of the above options - Click &quot;Pattern List&quot; tab to check eveything is OK and click Save 

Pattern List tab on Patterns Page - Allows you to compile a list of pictures (one at a time rather than a whole folder e.g. with #? or *.*), assigning a number Nr to one or more of them for easy reference. Using this number you will be able to assign the pictures to specific windows on the Defaults tab Page. If multiple pictures have the same number, one of the pictures will be chosen randomly. This will allow you to have random desktop pictures, random window backdrops etc. 

Defaults tab on Patterns Page - Here you can set the defaults for the background pictures for the Desktop, Screen, Window and/or Text Mode throughout Scalos. 
Randomize every time [check box] - Usually Pictures with the same number will be randomly selected as soon as the configuration loads. If this option is set, the picture will be selected as soon as a window with the same number assignment is opened. 

*Fit size: The picture will be resized to the dimension of the new window.You *MUST* have set GUIGfx on. asyncron layout: Pictures will be loaded and rendered while the windows opens (Like original Workbench). If this function is 'off', pictures will always be loaded before opening the windows. 
*Use friendbitmap : The picture is present twice in memory for best speed. This option has no effect if V43 picture.datatype or GUIGfx are used. Always relayout: If &quot;Fit size&quot; is set, the picture will be scaled everytime the window's dimensions change.
*Randomize everytime: Usually Pictures with the same number will be randomly selected as soon as the If more pictures have the same number, one of them will be chosen randomly. 

Patternlist New/Delete : Add a new picture. After that you should assign a number to it. The picture will be rendered as tiles. configuration loads. If this option is set, the picture

Asyncron-Task priority: You can set the CPU priority for the Task if &quot;asyncron layout&quot; is set. 
&lt;pre&gt;
Desktop: Number of the Picture for the main window.
Screen: Number of the picture for the Scalos-Screen.
Window: Number of the picture for the Scalos-windows.
TextMode: Number of the picture for the Scalos-windows in Text Mode.
&lt;/pre&gt;


Popup Menu preferences fully configurable menus (includes ToolsDaemon and ParM launch apps import), including support for context-sensitive Popup menus configs for top pull down menus for apps, etc. 

 Workflow - Scalos_Prefs then Menu, New Item, New Command add name at top then in Command Properties e.g. add Workbench and location e.g. DOpus:DOpus4 for apps  Command for c apps or Rexx for scripts or Plugin for  or AmigaDos for modules 

&lt;pre&gt;
DESCRIPTION	NAME/A      This is the title that is displayed in the top line of any popup menu  
INCLUDE NAME/A          Name of file to be included. Path can be relative to &quot;Scalos:FileTypes&quot; 

POPUPMENU      Starts the popup menu description section for this filetype.
&lt;/pre&gt;

The following Subcommands are allowed inside popup menus:
&lt;pre&gt;
SUBMENU &quot;NAME/A&quot;
ENDSUBMENU 


MENUENTRY &quot;NAME/A,KEY/K,DEFAULTACTION/S&quot;
ENDMENUENTRY 

INTERNALCMD	&quot;NAME/A&quot;
WBCMD &quot;NAME/A,STACK/K/N,WBARGS/S,PRI=PRIORITY/K/N&quot;
AREXXCMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;
CLICMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;

ICONWINDOWCMD &quot;NAME/A&quot;

PLUGINCMD
MENUSEPARATOR

ENDPOPUPMENU

TOOLTIP 
ENDTOOLTIP
&lt;/pre&gt;

&lt;pre&gt;
Starts the tooltip description section for this filetype. The following Subcommands are allowed inside popup menus:

GROUP &quot;ORIENTATION/K&quot;
ENDGROUP  
MEMBER &quot;HIDE/K&quot;
ENDMEMBER  

HBAR 
STRING &quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;
SPACE &quot;SIZE/N/A&quot;

DTIMAGE &quot;FILENAME/A&quot;
&lt;/pre&gt;


Each theme drawer (folder) has these further folders 
&lt;pre&gt;
About            - 
Desktop          - 
FileTrans        - 
FileType         - 
Icons            - 
Menu             - 
Modules          - 
PointerIcons     - 
Prefs            - 
Sound            - 
Window           - 
&lt;/pre&gt;


*Plugins
&lt;pre&gt;
devicefilter.plugin       
persist.plugin            should a crash or reboot occur - next time Scalos started, all windows re-opened 
title_clock.plugin        add digital clock to title see more below 
title_envvar.plugin       %ev, which can be used to display the value (a string) of the variable in the titlebar 
title_freepens.plugin     
volumegauge.plugin        
wb39.plugin               
wbrexx.plugin             plugin adds a Workbench 3.5+ compatible AREXX interface to Scalos internals 
xtwindows.plugin          left or right ALT or left or right SHIFT keys when open/close windows 
filetype.plugin           then run FileTypes-prefs and customize the filetypes (eg import from a DefIcons-brainfile) 
menu.plugin               
&lt;/pre&gt;


*Modules - delete, empty_trashcan, execute, find, format_disk, information, iconproperties, newdrawer, reboot, rename, systeminfo, windowproperties 


*Tools - scripts like LoadWB, quit.rexx, open_volume.rexx, 


In Scalos_Prefs-&gt;Filetype-&gt;Recognition  you can define the filetypes and on &quot;Action&quot; you define specific context menu for all filetypes defined in recognition (similar to magellan)
there is the same you must show all first (list is only limited) so you created a file type AAABBB, you need to have def_AAABBB icon 

Associating files with &quot;Scalos_FileTypes&quot; is very simple, practically it is very similar to Dopus4, first you create the Def_icons to assign to the file type (will be seen automatically ), then run &quot;Scalos_FileTypes&quot; you add the extension, fill in the descriptor (MATCH or PATTERN etc..) and save 

then you create a appropriate entry in the list and rename it, if def icon exists it is shown. Below you can define how files are identified. I use &quot;pattern&quot;, similar to magellan to identify file by ending. Then you click on the shown icon and define in it what program is used when you double-klick on it and save it. On the tab action you can define popup menu for it. 

defined all archive types from XAD in &quot;filetypes&quot;. If you change to &quot;action&quot; and click on &quot;archive&quot; you can define the context menu that is shown if you do not define a specific context menu for a filetype


Reset to Default in Scalos_Prefs resets all settings so BEWARE 


&lt;pre&gt;
The Scalos desktop screen titlebar may be configured using the main Scalos Preference program. This oop/time_clock plugin adds some additional placeholders:

    %ti, displays the current time in the default Locale format. e.g. &quot;10:43:37&quot;
    %da, displays the date in the default Locale format. e.g. &quot;Saturday 14 July 2001&quot;

Using the supplied prefs program for the plugin, or editing the ASCII file ENVARC:Scalos/title_clock.prefs you can use the following standard Amiga Locale values to change the formatting 

    %a - abbreviated weekday name
    %A - weekday name
    %b - abbreviated month name
    %B - month name
    %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
    %C - same as &quot;%a %b %e %T %Z %Y&quot;
    %d - day number with leading 0s
    %D - same as &quot;%m/%d/%y&quot;
    %e - day number with leading spaces
    %h - abbreviated month name
    %H - hour using 24-hour style with leading 0s
    %I - hour using 12-hour style with leading 0s
    %j - julian date
    %m - month number with leading 0s
    %M - the number of minutes with leading 0s
    %n - insert a linefeed
    %p - AM or PM strings
    %q - hour using 24-hour style
    %Q - hour using 12-hour style
    %r - same as &quot;%I:%M:%S %p&quot;
    %R - same as &quot;%H:%M&quot;
    %S - number of seconds with leadings 0s
    %t - insert a tab character
    %T - same as &quot;%H:%M:%S&quot;
    %U - week number, taking Sunday as first day of week
    %w - weekday number
    %W - week number, taking Monday as first day of week
    %x - same as &quot;%m/%d/%y&quot;
    %X - same as &quot;%H:%M:%S&quot;
    %y - year using two digits with leading 0s
    %Y - year using four digits with leading 0s

 like %d %m %y or %a %d %B %Y %p
&lt;/pre&gt;


Shutdown -&gt; right mouse button Scalos, About, Reboot, Shutdown 


ToolTypes can be added to the Scalos.info icon like 
*SCALOS_PATTERNNO=&lt;number&gt; : background image matching the number 
*SCALOS_NOTEXT : The Icon will be drawn without Text.
*SCALOS_NODRAG : The Icon will not be draggable. Its position will be fixed.
*Module iconproperties - Added SCALOS_BROWSERMODE tooltype support

runcommand parameters... in which case:
&lt;pre&gt;
%p = parameters
%w = directory path
%d = device-name
%% = literal percentage token
&lt;/pre&gt;


With the help of the wbrexx.plugin Scalos gains support for more of the compatible arexx API 

If an arexx command produces an error you will find the error code placed in the WORKBENCH.LASTERROR variable.

ACTIVATEWINDOW
&lt;pre&gt;
/* Activate the root window */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the &quot;Work:&quot; partition's window if already open*/
ACTIVATEWINDOW &quot;Work:&quot;
&lt;/pre&gt;

CHANGEWINDOW
&lt;pre&gt;
/* Change the root window; move it to position 10,30. * and change its size to 200100 pixels */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window */
CHANGEWINDOW active 20 40 200 100
&lt;/pre&gt;


Most of Scalos' issue are due to the flexibility of its' user configuring nature but if 


The sort menu plugin needs to be ported from ASM to C.

IIRC Scalos has a command line option to fully replace Workbench/Wanderer.

The Theme: assign is used by both Wanderer and Scalos but I didn't have any problems using both at the same time.


The Program will be started from the Shell.
If &quot;WB Args&quot; is set, with the Argument &quot;%p&quot; will be replaced by the path of the activated Icons. The Program will started with the specified Stack value.
IconWindow: Scalos opens the window of the specified path.


PlugIn: Starts a Scalos Menu-PlugIn.
If a Menu Item with empty name is specified, Scalos displays a separator line.
It's possible to Drag&amp;Drop an Icon in the Configuration Window. All values will be set accordingly. Entries may be dragged across the list.


Mac-like selection : This function activates a multiselection method used on MacOS or Win95. Don't have to hold down shift to drag them. Clicking on an already activated icon will
not deselect all other icons. 

MMB move: The window contents may be moved using the middle mouse button. 

WindowPopup title only: PopupMenu for windows can be opened only on window's title bars. 

FullBench: Screen-Titles removed and Main Window set Full Size. 
Scalos Prefs. Go to Settings-&gt;Scalos-&gt;Prefs and then the Misc section. Remove the tick against Full Bench. If you've enabled it, the titlebar will disappear when you select backdrop.


Default Icons saveable : The icons which Scalos generates if &quot;show all files&quot; is enabled, can now be saved
using &quot;snapshot&quot; menu option. load DefDisk first : Try to read the icons first from the DefIcons Path before using disk info. 


Hide hidden files : If this function is activated all files or directories where the &quot;hide&quot; flag is set will not be shown.

Many of my Icons display more than once on the screen, while on the workbench all seems ok.
The Workbench filters double displayed icons, Scalos does not. Solution: please edit the &quot;.backdrop&quot; file and clear double lines.

Background images not scaled. GUIGfx option not set or guigfx.library and/or render.library not installed.

If working with CD's causes crashs or Scalos doesn't work correctly.
Most Filesystems doesn't support the ExAll function correctly. Disable &quot;Use ExAll&quot; in Scalos prefs.

Scalos doesn't start any program in the WBStartup. WBStartup Path may be set wrongly or Scalos was not started in Emulation Mode (LoadWB etc) 
Some programs will not startup with error message &quot;has not returned, wait some more&quot;? and &quot;unable to open your tool&quot; 


need a def_icon with the same name predefined, then create an appropriate entry in the list and rename it, if def icon exists it is shown. Below this can define how files are identified. 
* either &quot;pattern&quot;, similar to magellan to identify file by ending
* or 
Then click on the shown icon and define in it what program is used when you double-click on it and save it. On the tab action you can define popup menu for it. All in all handling is of course different to magellan but can do similar 

For the RAM Icon, to obtain this you have only to copy the icon in the Icon Path as &quot;RAM.info&quot; or &quot;Ram Disk.info&quot;. All functions will automatically be performed 

sometimes cut into half or quarters when scrolled off screen or drawers moved - settings issue probably  

Sometimes leaves initial drawer window imprint on desktop when moved - settings issue 


Scalos AROS released a [https://github.com/deadwood2/contrib/tree/master/scalos new build V2022-07-21] with the following changes noted:
&lt;pre&gt;
Fixed:
    Numerous crashes when working on 64-bit with 64-bit heap
    Wrong background color of Scalos logo on Scalos splash window
    Backgroung image of Scalos splash window and Scalos About window is not visible
    Icon labels on desktop and in drawer windows are displayed using Topaz instead of Arial font
    Font.prefs are not being loaded on 64-bit
    Font.prefs are being wrongly saved on 64-bit
    scalos.prefs are not being loaded on x86 and x86_64, scalos is using always default preference
    scalos.prefs are being saved on x86 and x86_64 in format not compatible with m68k 
    NewPopupmenu.prefs is wrongly written
    Plugins are not loading at Scalos startup
    wbrexx.plugin is crashing at startup on 64-bit
    Multiple controls missing on Scalos Prefs/Icons page
    System crash when clicking on def icon image on FileTypes Prefs/Recognition page
    Status bar, control bar, buttons sometimes don't have images displayed
    Buttons in Scalos About window have white corners rendered where they should be transparent
    Crash when leaving out an icon
    Crash when adding a User-defined Button to Control bar without setting it's properties in Scalos Prefs
    Crash when removing any button from Control bar in Scalos Prefs
    Scalos Prefs allows editing TTEngine font properties when TTEngine is not present causing crash in Icons/Labels and Text Windows/Fonts pages
    deficons.prefs are not being loaded on x86 and x86_64
    Reset to default in FileType Prefs and Save does not save preferences

Won't fix:
    Scrollbars visible on titles of TrueType Fonts, PopupMenu, Menu, FileTypes, Pallette and Pattern pages of Scalos Preferences

Not fixed:
    Wrong rendering on DualPNG icons 
    Refreshing drawer windows is slow 
    Starting Prefs/Locale or Prefs/Input from Scalos causes other preferences to fail 
    Desktop wallpaper is damaged where Splay window was displayed 
    When started from Wanderer, after saving Scalos Prefs, reload does not re-open main Scalos window
    Difference in behavior between Cleanup from popup menu and Cleanup from top menu - possibly due to missing plugin, check Cleanup association in Menu Prefs
&lt;/pre&gt;


===DOpus 4 Directory Opus===

Copy DOpus4 app to WBStartup directory folder so it starts on boot up each time 

Another method is add the below to the bottom of the user-startup script in S: drawer/directory 
&lt;pre&gt;
run DOPUS:DirectoryOpus -i &gt;NIL
&lt;/pre&gt;
makes DOpus starts up in Iconified state at the top of Wanderer's screen. Left click on this to highlight and right mouse click to open. 


Just click on the sides of either outer edges of DOpus windows and it will display the parent device/volume list. 


DOpus saves it features in a CFG file which can be edited to suit anyones' needs by reading the [http://archives.aros-exec.org/index.php?function=browse&amp;cat=utility/filetool Dopus Manual] which is in Guide format. 


===BoingIconBar===

User chooses the apps to add to the dock at the centre bottom of the screen but has to be done manually, please use Save afterwards 

Or easier edit the text file of SYS:Prefs/Env-Archive/iconbar.prefs and save 

&lt;pre&gt;
SYS:System/Shell 
SYS:Tools/DOpus4/DOpus4
SYS:Utilities/Editor
SYS:System/SysMon
SYS:System/Scout
Work:Extras/Internet/OWB/OWB
Work:Extras/Graphics/Lunapaint
Work:Extras/Graphics/ZunePaint
AROS:Tools/MPlayer/MPlayer
Extras:Internet/AmiFox/AmiFox
&lt;/pre&gt;

right mouse click on bottom edge of screen where boingiconbar shows - select settings which opens BoingIconBar Preferences to add apps 

If no dock showing Add, to add apps click Add Program and search for the executable 

another method is to drag icons to ends of the bar and move them on the Bar using the Prefs/BoingIconBar 


===AmiStart===

On 32bit PCs only - auto generates the apps menu but scans the drive each time - AmiStart can choose apps you are not interested 

* how to disable annoying zune/mui 'bubbles'? 
try a right-click on AmiStart and release on Global settings. Then click on the bubbles gadget. Move the Show Bubbles slider all the way to the left.


===Fonts===

Install the #?.ttf files to SYS:Fonts/TrueType. Use SYS:System/FTManager to &quot;Install Font&quot; each #?.ttf file which will generate associated #?.otag and #?.font in SYS:Fonts. Use SYS:Prefs/Fonts to change system fonts and SYS:Prefs/Zune to change others. 

To achieve our goal we will use the Setup Locale, Input, Zune and Fonts, as well as The FTManager.

Begin

The first step you should do is to get the system to know that we speak and write in another language. What you need to do is to open the setup program and choose Locale country, and list &quot;preferred languages&quot; to put it first and then English. If you want the tab &quot;Time Zone&quot; and select city of residence to set the clock correctly. Of course we save our changes and continue opening the setup program Input. This sets the keyboard language as our beginning. When the language layout was created there was no option to switch to Aros keyboard (layout switching), so to write in the language you had to hold down Alt, something you encounter in other functions. This time working with the team of Aros to create a new keyboard layout to replace the old so we can get rid of the button Alt. For now though let only selected this layout and do not turn the switch on the keyboard.


Custom Keyboard Layout

[http://repo.or.cz/w/AROS.git/tree/HEAD:/workbench/devs/keymaps keymaps are in place but unfortunately when they are not, then indeed things become a bit 'low-level' as it involves redefining some tables with values that match your keyboards] 

only need to add your compiled table as new keymap. 

So taking a little peek here shows that it should be possible to compile using
 gcc -opc105_tr pc_105.c -nostdlib
where the pc105_gr/pc_105.c needs to be replaced with your own adjusted keymapname/c-file

[https://en.wikiversity.org/wiki/Enabling_Greek_Characters_on_Your_Keyboard General overview of Greek letters on keyboards] 


Installing fonts

*[http://aminet.net/package/util/wb/EPAGrWb System jaggy] 
*Outline resizable .font .otag 
In this step you need to download some fonts that can support the encoding in our system. The easiest way is to run the script &quot;Download Fonts&quot; you'll find in the folder OWB. This script downloads from the Internet, and unpacks some fonts for OWB web browser, which is placed under the folder Fonts:TrueType. But as these can only be used by OWB and not the system, which unfortunately does not see. To make them available to the rest of the system, open the program FTManager, you will find the folder AROS: System /. From there select the field &quot;Codepage&quot; option &quot;ISO-8859-7&quot; and list the font &quot;Arial&quot; and &quot;Regular&quot; form in which you must double-click with the mouse. In the window that appears, select the bottom right the checkbox &quot;Anti-aliasing&quot; button and then &quot;Install&quot;. Immediately folder Fonts: created files &quot;arialregular.font&quot; and &quot;arialregular.otag&quot;, which are necessary in order to see the system font. Do the same steps if you wish for other fonts.


Final stages 

After completing the above, open the folder AROS: Prefs / and run the program settings Fonts. In the new window, select the fields &quot;Icons&quot; and &quot;Screen&quot; as the font &quot;ArialRegular&quot; to the size you want. In the field &quot;System&quot; to give &quot;s_courier&quot;, which, however, because it is not True Type Font support Antialising, and may seem a little broken. You can also use the CourierNew, if you have installed the above procedure. After you save the changes and open the Zune program settings. In this set the &quot;ArialRegular&quot; font fields in tabs &quot;Windows&quot; and &quot;Groups&quot;, and save the changes. Reboot the system. To make sure that the above worked properly run NoWinED, which you will find under the folder AROS: Tools /. If that everything is working correctly you will see the menu and the settings window with Greek letters. You can also write in the language using the button Alt. Second program that you can try, which is fully localized, is WookieChat, which you will find in the folder AROS: Extras / Networking. And in this place all the menu and settings window works. 


===Windows===

*Intuition
The window you position and resize, you right click on that windows title bar and in the dropdown menu you snapshot from there.  Right click to show menu -&gt; Window -&gt; Snapshot Windows or All but it will NOT work if that folder has no icon (e.g. Disk.nfo) attached to it. You need a folder icon. The window information gets saved in it.  

As for maximising the window using a shortcut key - Alt and up arrow key 

The AROS-Shell windows can be moved, resized by editing sys:s/icaros-sequence 

&lt;pre&gt;
; run shell
if ${Icaros/autoshell} EQ true
  run QUIET c:newshell &gt;NIL:
EndIF
&lt;/pre&gt;

; slimmer right aros the screen 
run QUIET c:newshell con:0/150//300/ &gt;NIL:

; top right corner scr-x scr-y win-x win-y
run QUIET c:newshell con:600/150//300/ &gt;NIL:


*Zune - AROS version of MUI
Magic Menu type functionality is implemented in IControl preferences editor: in the frame called Menus, switch type from Pull-Down to Pop-Up and/or iControl just tick the sticky menu option. 


Windows outside screens causing a problem either uncheck &quot;Offscreen move&quot; for windows in IControl prefs editor. Or use FKey commodity and define two key shortcuts: 

* the first using the command &quot;cycle windows&quot; (for example ALT TAB); 
* the second using the command &quot;rescue window&quot; (for example ALT F5). 

Now you can cycle windows until the one you want to rescue, and then &quot;rescue&quot; it: it will move back inside your screen. 


How to save the window size on wanderer (snapshot all, snapshot windows)

Same for icon position on wanderer, can't save the position. Icon position cannot be saved yet, but you should be able to save the window position and size. sys:prefs - wanderer icon has option to save window size on exit but just for dh0. To get saving working on (DH1: Extras:) partitions try deleting the dh1 disk.info file, then reboot. The system should create a new dh1 icon. 


* how to set up permanently 'view all files'?
As for viewing all files, removing disk.info for that disk did the job 

* how to list and kill processes (xkill would be useful) ? 
sys:Extras/System/Scout can kill apps 

sys:Tools/Commodities/Exchange can remove available commodities


* how to restore 'go up' button in wanderer window? (it doesn't show up anymore).
If you're using Icaros, go to the theme prefs and make sure that decoration is checked. Also, some themes do not use a parent button, so try another theme. You may have to restart Aros before the theme will change.

* Is it really safe to turn off (hardware button) computer at any time (worried about USB hard disk)
yes you can turn off the computer IF none of the drives are in progress (i.e. writing). Best to use Wanderer menu option Quit otherwise 


===Say narrator===

SPEAK: is a write-only DOS device for text-to-speech abbreviated as tts. 
To check if available, type assign into the shell and at the bottom in the Devices: section should be SPEAK 

Examples of use 
&lt;pre&gt;
Copy S:Startup-Sequence SPEAK:
Echo &quot;Hello&quot; &gt;SPEAK:M/R/S150/P110
Echo &quot;DH1 EH0 L OW1&quot; &gt;SPEAK:A1
&lt;/pre&gt;

Classic options are M/F, R/N, S&lt;rate&gt;, P&lt;pitch&gt;, O0/O1, A0/A1, and D0/D1. O1 recognizes lines beginning with OPT/ as option changes. A1 treats input as narrator phonemes.

Long options select a speech engine:

Echo &quot;Hello&quot; &gt;SPEAK:ENGINE=narrator/VOICE=female/STYLE=natural/LANGUAGE=en-US

Supported selectors are ENGINE=, VOICE=, STYLE=, and LANGUAGE=. Values are case-sensitive backend identifiers. ENGINE=DEFAULT selects the system default. Narrator-compatible selectors continue through the classic translator/narrator pair. Other engines use speech.device. Direct phonemes require a narrator-compatible selection.


===Printing===

This needs further drivers written, we have postscript and write to file support only 


*Postscript

Best to set Printer Prefs in the Prefs drawer to print-to-file or parallel/USB port 


Save document in postscript or convert picture/text to postscript 

Print using compatible [http://en.wikibooks.org/wiki/Aros/Platforms/AROS_USB_support#printer.class_-_PostScript_3_and_internal_ghostscript_drivers Ghostscript printer] or Postscript printer 


*GutenPrint

Some work has been done 

;There are no individual drivers yet for HP's Photosmart, EPSON's EPL, CANON's, Lexmark, CUPS PPD, etc. 


*printer is simply not accepting IPP connections at the moment.

Please try the following steps:

Open the printer web interface in a browser:

 http://192.168.1.x/

Look for the network or protocol settings.

Enable IPP / Internet Printing Protocol.

Make sure TCP port 631 is open/enabled.

Save the settings and reboot the printer if the web interface asks for it.

 ipp://192.168.1.xx:631/ipp/print

 ipp://192.168.1.xxx:631/ipp/


===Files===

====File endings and datatypes====

* Check if the file has his own .info icon file with a tool set to open it. IIRC this has higher priority over the def_XYZ.info file association. 
* In ENVARC:SYS/def_Text.info or whatever def_ file needs changing, use Wanderer's menu Icon -&gt; Information and change the def_XYZ.info there. If you're on ABIv0 and want it to be applied immediately, you might have to copy it to ENV:SYS/ (or to reboot). 
* Identifying file types by file ending is only a fallback. Far better it is to search for magic words, for flac files this would be &quot;flaC&quot; according to this [http://flac.sourceforge.net/documentation_format_overview.html documentation]. 

For instance, to open PDFs with arospdf not localised in the default drawer of Icaros (Work:Extras/Applications/arospdf) but localised in a custom drawer in AROS. The default tools are defined in the icons in sys:prefs/env-archive/sys e.g. def_PDF. 


File type identification is done by datatype descriptors which you can find in Devs/Datatypes. The AROS build system has a tool which creates such datatype descriptors. 


'''Changing of default tools of existing icons is easy as shown above. Adding of new file types is not hard, but needs knowledge of the AROS build system.'''


The enduser way would be to download the attached file, which contained two executables:
1) createdtdesc, to make a new datatype description
2) examinedtdesc, to read/show existing datatype descriptions

use 2 to get an idea on how it things are currently done in aros by providing this executable a file from the drawer sys:devs/datatypes/ (alternatively you can find the original .dtd files here).

use 1 to make your new datatype. Use the accompanied FORMAT file (also here) to read how to make your own datatype descriptor. use 2 to get hints from other datatype descriptors.

Note:
When creating a new descriptor would advise against using the pattern property, but instead use the default pattern of #? and create a Mask that matches your filetype. This requires some research in order to discover how your filetype can be recognized properly. Of course with making something like a descriptor for an ascii textfile, you would fallback to using the pattern (e.g. #?.text as the filetype cannot be determined easily otherwise). 

&lt;pre &gt;
# name - choose wisely and informative. also used for icon's name.
# version - choose as you like as long as it complies with version rules
# basename - the 'root' datatype class. be aware that e.g. it can influence behaviour. for example when choosing binary and using tool multiview in project icon, the file will be viewed as binary file (choosing sound would tell mulitview to view the file as a soundfile). So this can influence the underlying tool being used. Could become messy if users started to modify the tool manually. 
# pattern - This is the file pattern match e.g. #?.text
# Mask - A mask to identify the file. Requires knowledge of the actual file structure. For example 'M' 'Z' for an msdos executable.
# GroupdID - not supported (AROS native) files - use syst as that would be the least intrusive in case an AROS tool/program tries to load such datatyped file.
# ID - In your case, the first four characters of the name at subchapter 1 (in lower case) (or less if name is shorter).
# flags - How the mask needs to be interpreted. In your case would be mostly DTF_BINARY in combination with (wanted or not) DTF_CASE (to tell if mask used letters are case sensitive or not)
# priority - the priority of how the type is handled so that on datatype could have precedence over another? In any case, document tells it to be mostly 0. 
&lt;/pre &gt; 

Now that you know each field and what it does (more or less), you write this fields in a text file for your own invented datatype, save it and create the actual dt with the tool in 1. in the end the created dt must reside in sys:devs/datatypes/ drawer.

Then you would create a default icon in sys:prefs/Env-archive/SYS drawer. Don't forget to reboot or copy .info file to ram:env/sys in order to test. also don't forget to set which tool to start f.e. c:lx or dh4:emulators/mycoolemulator

To test, open Wanderer then show all files and doubleclick on a file of type you just created. Alternatively you could use the 'open' command from shell (with file of datatype you just created as parameter).

And as a last note. it would perhaps be welcome to have a program like xicon and/or runprglist for AROS (unfortunately both without source, but something similar could be created for AROS).

Sounds complicated ?

Perhaps... but OS like windows needs a complete registry to be able to do things like this. And yes, i am aware windows has gui tools that does it (more or less) for you (by manipulating the registry). Same could be done for AROS (without integrating a registry in AROS that is ).

Would that suffice ?

red1+2: typos, reformatting.

disclaimer: please note that using these tools can screw up your currently installed support for datatypes when used incorrectly. Do not use if you do not understand what you are doing. Use at own risk.


==Network Connection==

AROS currently only has one real choice for TCP/IP networking - AROSTCP.  This is a port of the AmiTCP package from AmigaOS (TM), with a number of enhancements/fixes from AROS developers. 


 Please use Prefs/Network to set up wired, wireless or USB networking 
 Non USB wifi is easier, USB wifi can be an annoyance - remember to save whilst in prefs 


===Wired===

=====IPv6=====

Some support 


128bit IPv6 address packet 
&lt;pre&gt;
Local FD::/8
Global 2000::/3
64:ff9b::/96
&lt;/pre&gt;
NAT64 translates IPv6 to IPv4 
DNS64 


OS routing works with 
&lt;pre&gt;
MacOS Ventura 
Windows 11 with cloud account 
Ubuntu Jammy Jellyfish 
Android 10 (block google dns) 
&lt;/pre&gt;


====IPv4====

The top half of the IPv4 Configuration tab on the Network Prefs deals with the network card/USB and the lower half the router part. 

[[File:AROS Wanderer Network Prefs DHCP.png|thumb|DHCP Settings]]

'''Upper part of IPv4 tab''' 
* Click Add on the top right of the Prefs which opens a window called '''Interface''' 
* Enter Name as net0 (but can be anything as long as it is consistently used in other sections) 
* check mark on Active
* select device to be used using the '''right hand-side gadget''' of the box where the device name will go 
* set Unit to 0 
* IP Mode is default set to '''Get address from DHCP''' 


* IP Mode set to Manual if DHCP does not work automatically 

From the shell CLI,  ifconfig -a

Under net0: section, inet starting 192.168.x.xxx

* inet or '''Address''' of network card 
* netmask convert to decimal so 0x'''ffffff7f''' becomes 255.255.255.247 which is used to adjust the above '''Address''' into 
* broadcast 192.168.xxx.xxx

click OK


[[File:AROS Wanderer Network Prefs Manual.png|thumb|Manual Settings]]

'''Lower part of IPv4 tab''' 
* IP Mode Get address from DHCP (default) 


* or changing to Manual if automatic DHCP set up does not work 
* '''Gateway''' (Router Internal LAN-IP) (Default Route) = 192.168.0.1 (D-Link Netgear), 192.168.1.1 (Linksys 3com), 192.168.2.1 (SMC Microsoft), 192.168.1.254 (Belkin), 192.168.123.254 (USRobotics) else check with your router manual 
* first DNS = use 208.67.222.222 (opendns) or Gateway number above (to test web browser access to router) or 212.50.160.100 (google)  i.e. or whatever your ISP needs you to set 
* second DNS = use 208.67.220.220 (opendns) or Gateway number above (to test web browser access to router) or 213.249.130.100 (google) i.e. or whatever your ISP needs you to set 


* At the bottom of IPv4 tab, check mark the '''Start networking during system boot''' option 
* Save and reboot (sometimes Network restart fails, so reboot every time to be sure) 


'''an alternative way''' to AROS ifconfig -a, other OSs have similar for the same internet connection. Another connection will have different settings. 

e.g. From [http://www.ncsu.edu/resnet/windows/ipconfig/ Windows], '''ipconfig /all''' 
and note down the IP, subnet mask, default gateway, and DNS servers values and put these values in &quot;manually&quot; into AROS Network prefs. 

e.g. From Linux via dhcp router have a look at etc./dhcpc/dhcpcd-eth0.info 
* for manual input look at /etc/networks (IP or Gateway) and /etc/resolv.conf (DNS) 

 Please note that all in one routers (wired+wireless) or separate routers may need different settings 

IPv4 involves routing (192,168.x.x), firewall, NAT 


===Wireless===

[[File:MyArosWirelessSetup.png|thumb|Setting up]]

[[File:MyArosWirelessTCP.png|thumb|Shell commands to work out what is happening]]

We must first make certain you have a Atheros 5k chip inside acting as the wireless wifi option. Open PCITool in Tools directory. Down left hand side are a series of numbers 0.00.0 etc. Click on some at the bottom and hopefully one of them will say Atheros AR5??? or AR242?. 

or a Realtek RTL8187B, we can check using Prefs/Trident as this one is USB based 


There are many similarities with the above Wired set up so please read the above section as well 


* open Network/Prefs
* In '''IPv4 Configuration''' tab - click Add - enter net0 / active tick / #?.device / Unit 0 / IP Mode = manual (important if default DHCP does not work automatically) 

Make sure that any extra network names (e.g. eth1 or net1) should be deleted. If net0 already st previously, change net0 so that it shows associated with the appropriate device name like atheros5000.device or realtek8180.device. Having two entries here will cause sub-net problems. 

* Go to '''Wireless''' tab and click on &quot;Add&quot; button. 
* Insert network name (SSID your wireless network name use wirelessmanager to get it), select right &quot;encyption&quot; that is most likely &quot;WPA&quot;. 
* Key Type set as &quot;Passphrase&quot;. i.e. type in your password for your router (aka access key). 
* Unselect (no tick) &quot;hidden&quot; if it is selected, then apply. You may have to tick it if wireless does not work. 
* Finally, Save and '''reboot'''. 

For the best chance of success, set networking to start at boot, and then reboot with the USB adapter plugged in. 


===USB Ethernet===

Open SYS:Prefs/Network and in the IPv4 Configuration tag (top table covers your usb stick) 

* click Add button
* set Name as net0
* Tick Active box
* enter the usb-ethernet.device e.g. dm9601eth.device, usbpegasus.device or usbasixeth.device use SYS:c/devlist, '''Scout''' or trident prefs to get the correct spelling 
* set Unit to 0 (which is usual but check the messages from the bottom of the Trident prefs whilst plugging the device in to determine the unit number otherwise) 
* IP Mode is set to Get address from DHCP (make sure your router is set right for that) 
'''or manual'''
* IP Address of network card, i.e. 192.168.0.xx or 192.168.1.xx (xx being greater than 1) 
* Subnet netmask = 255.255.255.0 
* click OK

There can be sometimes be boot failures when using USB ethernet - plug the USB device in after boot and save the network prefs to make it work again. 


Lower part of IPv4 tab covers the router information 

* IP Mode Get address from DHCP 
'''or if manual settings'''
* Gateway (IP Address of router) = usually 192.168.0.1 or 192.168.1.1 but see router manual to make sure. 
* first DNS = use 8.8.8.8, 208.67.222.222 (opendns) or 212.50.160.100 
* second DNS = use 8.8.4.4, 208.67.220.220 (opendns) or 213.249.130.100 


===USB Tethering via Android smartphone===


Go to AROS Network Prefs (IPv4 configuration tab) and write type in &quot;usbrndis.device&quot; in the &quot;device&quot; textfield of &quot;Interface&quot; sub-window, which appears when you add a new device (or modify an existing one). Select &quot;Start Network during system boot&quot; and saved the configuration, the Connection is immediate no reboot is needed.&lt;br&gt;

usbrndis.device is a resident device (virtually always there) in fact, a driver is not present in DEVS:Networks &lt;br&gt;&lt;br&gt;

Plug in USB cable, go to Android settings and enable &quot;USB Tethering&quot; &lt;br&gt;

A reboot should not be necessary.

When restarting AROS, the Smartphone deactivates the connection and to access the network again have to reactivate it before starting the browser. 


===Solving Issues===

[[File:MyArosTCP.png|thumb|Aros network setup diagnostics - why does it not work?]]

* In Network Preferences, have '''only one''' item in the IPv4 Configuration tab 
* If using manual settings, make sure all numbers are correct, especially for IP address of the card/usb (changing the last number in chain of four) 
* For any USB based networking, it is often necessary to save in Prefs/Network, reboot AROS and network support can begin 


* For wired, make sure that the LAN-cable is plugged in before starting the computer 


* If wireless, try getting closer to the router. 
* Switch off the encryption option from your router then try wifi, if successful then your ip/dns is ok. If not then your ip/dns settings are most probably wrong or need to use one or more opendns numbers 
* Replace detachable wireless antenna (best wireless option to buy if you can) with a stronger antenna ie. 5&amp;nbsp;dBi or 7&amp;nbsp;dBi 
* Try with another computer/laptop/machine 

Program Error  C:WirelessManager 

* Test with another OS 
* Check that Wifi works before changeover (if possible) 
* Check that socket and card are working 
* Check if card is too new for laptop (date code on card MMYY blue askey date 2005-2007 etc)   


Are you connecting with the Router ? 

Check with protection off e.g. wps and wep to see if it makes a difference. 


For USB wireless - stopping and starting may be needed...

&lt;pre&gt;

; $VER: AROSTCP-startnet 1.0 (01/08/06)
; AROSTCP-startnet (c) The AROS Dev Team.
;
Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

; stop and restart
execute &quot;sys:system/network/AROSTCP/s/stopnet&quot;

Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

run &lt;NIL: &gt;NIL: wirelessmanager realtek8180.device

&lt;/pre&gt;


What IRQ number is assigned to the device? You can check with Tools/PCITool? 
It's possible the BIOS hasn't set the right IRQ number. If you have a Linux CD/DVD handy, could you check if it boots with the options &quot;acpi=off noapic nolapic&quot;? 


If the following does nothing, this will help us figure out why networking doesn't start automatically at boot

open a shell and run the following commands:

&lt;pre&gt;
echo ${AROSTCP/AutoRun}
echo ${AROSTCP/WirelessAutoRun}
echo ${AROSTCP/WirelessDevice}
&lt;/pre&gt;

Please report the output, typically it will look like this  

# True  (explanation this variable is related to the &quot;Start networking during system boot&quot; checkbox in network prefs) 
# True  ()
# Devs:networks/atheros5000.device unit 0


If there's a problem with the AROSTCP package. What's the output of this?

 ENV:sys/packages/AROSTCP 

should return a string = Sys:System/Network/AROSTCP


By the way, a quicker way to check networking is working would be to run some shell commands such as:


&lt;pre&gt;
ping www.google.com
ifconfig net0
&lt;/pre&gt;


The best way to list the available networks and diagnose / troubleshoot problems with connecting to a wireless network is to run WirelessManager manually. First uncheck the &quot;Start networking during system boot&quot; box in the Network prefs app, then save and reboot. Then run this in a shell:

 C:wirelessmanager atheros5000.device verbose 

or 

 C:wirelessmanager realtek8180.device verbose 

and capture the output 


If the above does not help, could you edit the file SYS:System/Network/AROSTCP/S/Package-Startup, and change &quot;&gt;NIL:&quot; to &quot;&gt;T:wifi.log&quot; on the WirelessManager line and add this as well Wait 5?

&lt;pre&gt;
if ${AROSTCP/WirelessAutoRun} eq &quot;True&quot;
Run QUIET &quot;C:WirelessManager ${AROSTCP/WirelessDevice} &gt;T:wifi.log&quot;
wait 5
EndIf
&lt;/pre&gt;

Then save, reboot and post the log file (T:wifi.log) here.


&lt;pre&gt;

c:wirelessmanager atheros5000.device verbose
Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7)
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'


Then it just sits there. Not sure what a normal dump looks like, I don't see anything that looks wrong in the configuration.
&lt;/pre&gt;

looks like the driver isn't working with that card. Has anyone else successfully used that exact model number (AR2413)?


&lt;pre&gt;

Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7):
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'
*** [wpa_sm_init] sm-&gt;pmksa=02c66fd4 ***
Own MAC address: 00:01:36:15:ae:0c
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
Added interface atheros5000.device:0
State: DISCONNECTED -&gt; SCANNING
Started AP scan for wildcard SSID
MLME: starting scan
MLME: scan channel 1 (2412 MHz)
sana2: sending MLME frame


Then it stops. Does this mean the router is not authorizing this NIC?

IRQ 4 (A)

&lt;/pre&gt;

apparently locking up when the first frame is sent (a scan request).


&lt;pre&gt;

Devs/Networks/atheros5000.device:0
Initializing interface 'Devs/Networks/atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=12):
41 69 72 4c 69 6e 6b 35 39 33 30 30 AirLink59300
PSK (ASCII passphrase) - hexdump_ascii(len=8): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='AirLink59300'
*** [wpa_sm_init] sm-&gt;pmksa=0224e444 ***
Own MAC address: 00:1f:e1:42:e3:7a
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
[eloop_reg_timeout] Timeout is at 1317686594.160000
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
[eloop_reg_timeout] Timeout is at 1317686595.060000
[eloop_reg_timeout] Timeout is at 1317686604.060000
Added interface Devs/Networks/atheros5000.device:0
[eloop_run] Starting
State: DISCONNECTED -&gt; SCANNING
Starting AP scan for wildcard SSID
MLME: starting scan
[eloop_reg_timeout] Timeout is at 1317686594.160001
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.233000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.373000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.513000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.553000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.693000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.013000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.073000
EAPOL: disable timer tick
EAPOL: Supplicant port status: Unauthorized
MLME: scan channel 14 (2484 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.113000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.153000
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.213000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.353000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.493000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.533000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.673000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.993000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686596.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686596.073000
MLME: scan completed

&lt;/pre&gt;

Is your network hidden? If so, did you enable the 'Hidden' checkbox in the network prefs? What distro version are you using? 


&lt;pre&gt;
&quot;ENV:sys/wireless.prefs&quot; looks like this:
network={
ssid=&quot;testadhoc&quot;
key_mgmt=NONE
wep_key0=&quot;12345&quot;
wep_tx_keyidx=0
}
&lt;/pre&gt; 


If your router doesn't broadcast its SSID (hidden), you need to add this option to the network block of the wpa_supplicant.conf on your aros machine and make changes after  # Example blocks: 

 scan_ssid=1

Here's a full description of all the [http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/wpa_supplicant.conf config file options]. 

&lt;pre&gt;
ap_scan=1

network={
ssid=&quot;YOURESSID&quot;
scan_ssid=1
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
group=CCMP
psk=YOURPASSWORD
}
&lt;/pre&gt;

&lt;pre&gt;
filter_ssids=1
ap_scan=2

network={
ssid=&quot;REMOVED&quot;
scan_ssid=1
bssid=REMOVED
priority=100
mode=0
proto=RSN
key_mgmt=WPA-PSK
auth_alg=OPEN
pairwise=CCMP
group=CCMP
psk=REMOVED
}
&lt;/pre&gt;


Error 6: Couldn't resolve host name.

Check Scout -&gt; Devices and look at the device that you are using, in the OCnt column it should state 2 which means AROSTCP and Wirelessmanager are both accessing this driver. If 0 or 1, then uncheck the checkbox in Network prefs for starting networking at boot, save and reboot. Then run this is the shell:

C:WirelessManager realtek8180.device unit 0


some quirks setting up the wireless network as well 

1) it's far better setting up either the wired OR the wireless network adapter as net0:, or weird things happen

2) it's better using fixed IP on the local network instead of DHCP

3) network setting must be placed in network setting panel in /prefs, using the wirelessmanager helped me finding available SSIDs, but not actually connecting to them

once done, reboot.


If previous setup is proving problematic 

&lt;pre &gt;

SYS:Prefs/Env-Archive/Wireless.prefs
SYS:Prefs/Env-Archive/Zune/OWB.config
SYS:Prefs/Env-Archive/Zune/global.config
SYS:Prefs/Env-Archive/AROSTCP/WirelessDevice
SYS:Prefs/Env-Archive/AROSTCP/db/Interfaces
&lt;/pre &gt; 

Make a copy of these files and restore in case of problems. 


Please try this test to check if you can connect to your router, ie established that the WiFi layer is working 

̊̊̊̊Boot with networking disabled, by make sure that &quot;Start networking at boot&quot; in Network Prefs is unchecked (no tick).  
̊ Run this in a shell: C:WirelessManager atheros5000.device VERBOSE
̊If the output of that command is too long to summarise here, you can redirect it to a file by adding &gt;RAM:wifi.log to the end, then attach or paste that file here.


try running &quot;status&quot; in the shell and check that AROSTCP is listed/running
If AROStcp is not showing, then AROSTCP is not running. attempted to start it by clicking Use or Save in network prefs, or checking the &quot;start networking at boot&quot; box or typing into a shell. 

 Execute SYS:System/Network/AROSTCP/s/startnet

(run Status again afterwards).


The &quot;cannot resolve hostname&quot; will appear if you are blocked on the wifi network by the router as well as aros not being able to assign correct network address.

One way of testing this might be to disable the firewall in the router. you might also check the router how it sees the attempts aros do to speak to it. The easiest way to do that would be to manually give aros an IP number in the routers accepted range. and see if it shows up at all within the router.


Tests that can be undertaken to determine correct settings and functions 

 pciinfo
 sanautil -d broadcom4400.device status

&lt;pre &gt;
 ping &lt;router-address&gt; e.g. 192.168.0.1 (aka inet) or 80.237.146.33 (www.amiganews.de) 
 ifconfig net0
 ifconfig net0 up
 extras:networking/utils/sanautil/sanautil -d atheros5000.device status
 WirelessManager atheros5000.device verbose &gt;RAM:wifi.log
 ;to send the log to RAM disk to be read easier or if detected, 
 Run WirelessManager atheros5000.device &gt;NIL:
 Run WirelessManager atheros5000.device ssid=&quot;mynet1&quot; &gt;NIL: 
 C:WirelessManager realtek8180.device unit 0 
&lt;/pre &gt; 

Please look at the task list in Scout, and check if WirelessManager and AROSTCP are running. Also look at the device list in Scout to check if realtek8180.device is open. 


start tools/debug/sashimi, maybe it shows some debug messages when disconnection happens.


Firstly, let's take a look at what your setup most likely looks like, assuming you use a router. See diagram below: 

&lt;pre&gt;
Internet &lt;---------&gt; home router &lt;---------&gt; computer 
-----------external IP------------------internal IP-------------
&lt;/pre&gt;

Okay, so what am I trying to show you with that diagram. A few things. Firstly, the IP address that connects you to the Internet is not the same one that connects you to your router. What happens is that your computer doesn't have a direct connection to the Internet, instead your router connects to the Internet, and your computer connects to the router.

You can see the external and internal IP addresses in these example settings...

* Default Gateway : 76.91.64.1 (external IP for ISP/Internet host)
* IP Address : 76.91.71.184 (external IP for home router)

* IP Address : 192.168.0.1 (internal IP for home router)
* Address = 192.168.0.161 (internal IP for computer)

As you can see, there are two internal IP addresses and two external IP addresses. This is because there is a client/server relationship, effectively one address is for the service (server) and one address is for the device trying to access that service (client).

The server addresses in your case are 76.91.64.1 (your ISP's address, serving the Internet), and 192.168.0.1 (your home router's address, serving your home network). The term gateway applies here, they are your gateway to those services.

Subnet masks are used along with IP addresses to determine which IP addresses are allowed access to a network. I did learn the more in-depth rules about subnet masks once (watched a CCNA vid), but I've forgotten about it. The basic level of understanding you'll need is easy to remember though. A subnet mask value of 255 means that portion of the IP address must stay constant, whereas a subnet value of 0 means any unassigned value up to 255 is allowed in the IP address.

By far the most common subnet value is 255.255.255.0. What this means is that the first three parts of the IP address you use to connect to a service must stay the same as the server/gateway address, and only the last section can change.

So if your router's internal IP address is 192.168.0.1, and the subnet mask is 255.255.255.0, the only addresses that will be allowed to be used on that network are between 192.168.0.2 and 192.168.0.255 (I think 192.168.0.0 is reserved for other uses).

Final point to make is about DHCP (a.k.a. dynamic IP) vs static IP. A server/router using DHCP gives a device that connects to it an address within the acceptable range. It usually starts with the lowest numbered free address, so with your router it'll give the first device that connects to it 192.168.0.2, the next device 192.168.0.3, and so on. Static IP addresses are where you set the IP address you want to connect with in advance. 

When using static IP addresses on a router where DHCP is active, it's good to use a high number to avoid conflicts with other devices that are connected to your network, to reduce the risk that both devices will try using the same IP. That's why your current choice of 192.168.0.161 is good, unless you have over 159 devices connected on your current network!


Okay, so what's the next step. Well, if you can use ping, I'd suggest pinging 192.168.0.1. If you get a positive response it means you're connected to your router, if you don't get a response it means the connection between your router and your computer is at fault.

Documentation on configuring the AROSTCP environment further can be found [http://en.wikibooks.org/wiki/Aros/User/Networking here] 


===File Sharing===

As AROS knows only a few filesystems (FFS, OFS, SFS, PFS (amiga only), FAT12, 16, 32, Microsoft NTFS (windows), UDF (Blu-ray)). 
The others in regular use like MacOSX hfs+, Linux ext2/ext3 and ext4, Haiku BeFS provide a problem in transferring files. 

Linux can access SFS partitions but it needs to be compiled. The latest full source are [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ here]. It compiled fine with a 2.6.30 kernel in Puppy Linux 4.31. 

An alternative, is to use a FAT32 partition to share. Setup a 4G FAT32 partition using HDToolbox for sharing, and the rest of the space as SFS for an Aros install. It works very well. 

Files could be transferred via TCP internet network. 


====SMB2/3====

With Windows you can share one folder or all folders of the &quot;Public&quot; user.

On Windows what is important is to enable sharing (Network and Sharing Center).

AROS Mountlist should look lke this 
&lt;pre&gt;
Handler = L:smb2-handler
StackSize = 65536
Priority = 5
GlobVec = -1
ACTIVATE=1
Startup = &quot;smb://UserAcc:password@PCShare/Sharefolder&quot;
&lt;/pre&gt;

which could also be
&quot;smb://UserPC:password@192.168.x.x/Public&quot;
or
&quot;smb://UserPC:password@Name-PC/Public&quot;

so
&quot;smb://UserPC:password@192.168.1.158/Folder&quot;
or
&quot;smb://UserPC:password@Name-PC/Folder&quot;


After you have configured a share generates a DOSDrivers it is named &quot;SMB0&quot; which includes the setting, and at each reboot it is Mounted. You can still delete the DOSDriver by hand, is located in Storage/DOSDrivers, the file &quot;ServerAutoMounts&quot;, in ENV:AROSTCP which indicates the DOSDriver to be mounted, should also be deleted. 
The per-mount files are written to ENV:SMB or SYS:Storage/DOSDrivers. There is also additional file ENV:AROSTCP/ServerAutoMounts which states what will be presented to the end user. 


====Old SMBFS====

e.g. to connect to a NAS share such as \\NASBOX\Shared use -:

SMBFS WORKGROUP=&lt;YOUR WORKGROUP NAME&gt; VOLUME=&lt;AROS volume name to use&gt;: SERVICE=&lt;UNC Path to connect to&gt;

SMBFS WORKGROUP=MYNET VOLUME=Shared: SERVICE=//NASBOX/Shared

And you will then have an icon appear on your desktop for the volume name you have chosen. 


You can put the above script into wbstartup or  

give it an icon, change it to a 'project' and give it the default tool c:iconx 

Open a shell and type copy sys:script.info &quot;sys:wbstartup/YOURSCRIPTNAME.info&quot;

This should create an icon for your script file.

Now right-click on your script and select 'information'.

Change 'tool' to 'project', put 'c:iconx' into the 'default tool' box, click save 

The reason being that scripts need to be opened with 'execute SCRIPTNAME' (or 'iconx') whereas the programs started from wbstartup are opened using 'run PROGRAMNAME'. It's the same as trying to start a command-line tool from the workbench by double-clicking it.


====Setup ISO images within AROS====

Use [http://archives.aros-exec.org/index.php?function=browse&amp;cat=driver/storage DiskImage] which supports many cd image formats ISO, CCD, MDF/MDS, CUE/BIN, NRG and UIF. To mount CD or DVD images use below....

&lt;pre &gt;
# Rename your iso 'Unit0' (note no extension).
# Do 'View/All files' on you Aros partition. You should now see a folder called 'Diskimages'. Copy your renamed iso to there. 
(Alternatively, you could type at the shell 'assign FDSK: xxx', where xxx is the location of your iso.) 
# From the shell, type 'mount CD0:' and the iso should appear on the Wanderer desktop. You can now access it like a real disk.
&lt;/pre &gt; 

 assign devname: dismount 
 Assign DOSVOLUME: remove
 [http://aminet.net/package/disk/misc/unmount-0.1 unmount] most filesystems work but SFS lacks support for ACTION_DIE packet 

If you are using an IcAros install, the startup scripts are set up to wipe the Diskimages directory on boot, so its worth keeping a second copy of the iso somewhere else. Alternatively, you could set up extra mountlists for additional iso images. I've made a file called iso1 in the Aros:devs directory that contains the following text:

&lt;pre&gt;
/* Entry for ISO image */

ISO1:
FileSystem = cdrom.handler
Device = fdsk.device
Unit = 1
LowCyl = 0
HighCyl = 0
Surfaces = 1
BlocksPerTrack = 1
DOSType = 0x41434400
Activate = 1
#
&lt;/pre&gt;

Then I just need an iso called 'Unit1' (corresponding to the 'Unit = 1' entry in the mountlist) in Diskimages (or wherever I assign FDSK: to) and to mount I type in at the shell:

 Mount iso1: from devs:iso1

Of course, if you create mountlists for ISO2, ISO3:, etc. (with the corresponding change to the 'Unit = ' line) you can have as many isos mounted as you wish. I just call mine ISO1: etc. to distinguish them from the real CD drives 


==Video Guides==


Video demonstrations and tutorials covering:

:00. '''Introduction''' 
::[https://www.youtube.com/@jamesmattson6813/videos Various Aros Installs], 
::[https://www.youtube.com/embed/j8EmSEby0Rg AROS repo in gource, view of AROS dev commits from 1997 to 2025], [http://www.youtube.com/watch?v=Vx_zqlBow40&amp;feature=related Gource view of AROS 1997 up to 2009], 
::[http://www.youtube.com/watch?v=s1RsvEm7UrU Why an Amiga OS in 2011], 
::[https://www.youtube.com/watch?v=1W886mheV74&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Johan Grip on early days of AROS x86], [https://www.youtube.com/watch?v=mXaKDhtTTqQ&amp;t=14s&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Michel Schulz on Aros and PiStorm], 

:01. '''Installation'''
::[https://www.youtube.com/watch?v=M7YjufrJqDs Aros One install], [https://www.youtube.com/watch?v=iIMguHTdC5E Aros One USB install], [https://www.youtube.com/watch?v=ZNXauy5m5Wc Aros One install], [http://vimeo.com/11013489 Modify Grub boot], 
::[http://www.youtube.com/watch?v=wyQVeyXIywc&amp;feature=channel iMica Silent Pt3], [http://www.youtube.com/watch?v=o2AnkoflY14 Wipe whole drive and Install - warning loss of data on drive], 
::[http://www.youtube.com/watch?v=OVXm6_-witQ VirtualBox install], [ VMware install], 
::[http://www.youtube.com/watch?v=0k2PEmT8I14 Broadway AROS Install], 
::[https://www.youtube.com/watch?v=PtDiXhjSIfs Is Aros Icaros a choice?], 
::[ driver install], 
::[http://www.vimeo.com/10491104 HDAudio install but needs account], [], 

:02. '''Amiga Basics'''
::[http://www.youtube.com/watch?v=TY8mWxwzH5o Screens tutorial], 
::[https://m.youtube.com/user/AMIGASYSTEM/videos General], [ Dos Scripts tutorial], [http://www.youtube.com/watch?v=hPT7SmVEpjc OS 1.2], [http://www.youtube.com/watch?v=n6kX3FqH8Ww&amp;feature=related OS 1.3], 

:03. '''Customisation demos'''
::[https://www.youtube.com/@AMIGASYSTEM/videos Prefs tutorial], [ Decoration tutorial], [http://www.youtube.com/watch?v=Dn5C8G3aDXU Scalos], 

:04. '''Setting up''' internet access and surfing the web, FTP, IRC and Mail apps 
::[ Network Prefs], [ AirCOS tutorial], [ jabberwocky tutorial], 

:05. '''Native bundled Games and Applications''' 
::[http://www.youtube.com/watch?v=aYlFv2B-VXc 3D Games], [http://www.youtube.com/watch?v=MXK7wwhd-R0 Latest Games], [http://www.youtube.com/watch?v=RUgiVThv23Q&amp;feature=mfu_in_order&amp;list=UL PrBoom GL], [http://www.youtube.com/watch?v=0s7u8TPy7V4 Assault Cubes], [http://www.youtube.com/watch?v=fih6aCXKeqs Cube 2], [http://www.youtube.com/watch?v=-X0ay0MGOms DosBox on Aros], [http://www.youtube.com/watch?v=7nKduDjf14k Oct 2010], 

::[http://www.youtube.com/watch?v=FziV2z_uxnQ Apps Pt 1], [http://www.youtube.com/watch?v=xs37_nfa5CI Apps Pt 2], [http://www.youtube.com/watch?v=Bn59_VvbQR0&amp;feature=related Apps Pt 3], 
::DOpus4 [http://www.youtube.com/watch?v=aSRybWjrrME DOpus 4], 
::Milkytracker [http://www.youtube.com/watch?v=VxBOEPzpdKg&amp;feature=related Laying Down Base Tracks], 
::[http://www.youtube.com/watch?v=k2uKQ0-ieOE Audio Evolution 4 in action], [http://www.youtube.com/watch?v=Zq4r9k0_jZI Quick Videos], 
::[http://www.youtube.com/watch?v=gGKCFZcIc0I&amp;feature=related ScreenRecorder], [http://www.youtube.com/watch?v=974c2e-Fqak&amp;feature=related TV out Tests], 
::[http://www.youtube.com/watch?v=fjq8ct5d5IY AmiFIG], [http://www.youtube.com/watch?v=h0rHvPhYJo4&amp;feature=youtu.be ZuneFIG], 
::[http://wiki.povray.org/content/Documentation:Tutorial_Section_1 POVray Tutorial 1], 
::[http://www.youtube.com/watch?v=Jk-ZNLfJsvQ pt 1, jan. 2008], [http://www.youtube.com/watch?v=nWRy33g1R7Y pt 2, feb. 2009], [http://www.youtube.com/watch?v=r5PbhCtm4vE pt 3, feb. 2010], 

::[https://www.youtube.com/watch?v=G7_FJUoQ89o Hollywood programming], [], [], [],

::[], [], [], 
::[], [], [], 
::[], [], [], 


:06. '''Commercial software available'''
::[http://www.youtube.com/watch?v=fKXY9B4R43s AntiryadGX 3D Game Editor], 
::[http://www.youtube.com/watch?v=TMS9NDzwm5U BOH indie Game], 

:07. '''Running classic amiga apps and games''' 
:: Amiberry [], [], 
::[http://vmwaros.blogspot.com/2008/11/introducing-amibridge.html Intro Amibridge], [http://www.youtube.com/watch?v=ee2PWvCZeLo Old Amiga Apps], [http://www.youtube.com/watch?v=ee2PWvCZeLo Why Janus UAE is good], 
::[https://www.youtube.com/watch?v=VhlsNSYSuDg DPaint tutorial]

::[http://vmwaros.blogspot.com/2009/11/can-icaros-play-my-amiga-games-and-why.html Play Amiga Games], [https://www.youtube.com/watch?v=XTaZCNOvCnE], 
::[http://www.youtube.com/watch?v=tMehS77LXQ4 Pagestream Introduction], [http://www.youtube.com/watch?v=284-w3hTzII Pagestream Tutorial 1], [http://www.youtube.com/watch?v=mlwEGwhZzl4 Pagestream Tutorial 2], 
::[http://www.youtube.com/watch?v=iIcrIjPOctc Catweasel Mk4 PCI Part 1] and [http://www.youtube.com/watch?v=BaitHeL6bEA Part 2], 

:08. '''Misc and History'''

::[http://www.youtube.com/watch?v=d6mDXKU29w0 Mum uses old AmigaOS Workbench 1.1 (1986)], [http://www.youtube.com/watch?v=DaRkacQ-YMg Why an Amiga 500 (1987)], [http://www.youtube.com/watch?v=k5CYsgVCzYY an Amiga 2000 (1987)], 

:09. '''Misc Shows and Events'''
::[http://www.youtube.com/watch?v=klgVSWKs4kE VCF 2010], [https://www.youtube.com/watch?v=eQ3d5qR-Hv8 24:06 Jason McMullan at amiwest 2012 about AROS], [https://www.youtube.com/watch?v=jpQO7XSfAv4 Aros SMP multi core amiwest 2013], [], [https://www.youtube.com/watch?v=gFRtAAmiFbE], [https://www.youtube.com/watch?v=DjdUEyjx8GM], [https://www.youtube.com/watch?v=ydYDqZQpim8], [], [https://www.youtube.com/@uminekoshouten/featured], [https://www.youtube.com/shorts/NfoY023w-vE], 

:10. 
::[https://www.youtube.com/shorts/6qJTNW4-6GY]


===History===

The project was originally started by a small group of Amiga [http://www.amigahistory.co.uk/aros.html enthusiasts] in 1995. These individuals were mainly computer-based college university students at the start, though that student trend has diminished since. An interview with Aaron Digulla [http://arosshow.blogspot.com/2006/12/interview-with-aaron-digulla-who.html here] 

* 1992 Commodore folds 
* 1996-1998 much of the early years was concerned with exec, dos and intuition libraries. 
* Early 1999, Haage &amp; Partner used parts of the AROS code in AmigaOS 3.9. 
* March 2001, floppy disk images of AROS became available. 
* Early 2002, AROS changed its name from Amiga Replacement Operating System to Amiga Research Operating System 
* June 2002, AROS devs decided to use Zune (MUI 3.8 rewrite) as the GUI system. 
* November 2002, Eric Schwartz drew Kitty for AROS usage. 
* Early 2003, AROS.org underwent a graphics facelift. 
* Late 2003, GCC C compiler arrived. 
* Early 2004, Aros-Exec opened. 
* Early 2005, Aros Max bootable CD arrived. 
* Late 2005, SFS filesystem ported and allowed fast access to apps and network support arrived 
* Early 2007, AROS.org underwent another graphics facelift. 
* Mid-2007, AROS changed to AROS Research Operating System after A.Inc. sued Hyperion with a trademark violation. 
* Late 2007, the hard disk installer added and VmwAROS (later called Icaros Desktop) distro launched. 
* Early 2009, Our first usable web browser (OWB)
* September 2010, first wireless support appears and AspireOS started as a distro 


* Early 2012, the first paper-cut bugfix and Fab's Odyssey Web Browser ported 
* Early 2017, work started on utilising the addition cores on modern CPUs starting with the 64bit x86 PC version  
* Mid-2017, m68k port optimized for the Vampire 2 / Apollo accelerators (68080 AMMX FPGA) 
* 2018 The old AROS Exec website closed and a new one opened 
* 2019 AROS One x86 32bit distribution started and now with USB install version 
* Early 2021, backport of more features of 32bit PC ABIv1 into 32bit PC ABIv0 (Aros One 1.5 and above) 
* 2025 year of 64bit pc builds and porting 32bit applications to 64bit ABIv11
* 2026 update of [https://www.youtube.com/watch?v=6FKTL068ULM&amp;pp=ygUPYXJvcyBhbWlnYSAyMDI2 nvidia nouveau driver for 64bit PC] 


===Bounties===

To help inspire developers with both ideas and monetary incentives, rewards are offered for the successful completion of &quot;bounties&quot; (requests for missing/new functionality) chosen by the community and handled by [http://power2people.org power2people] (formerly done by TeamAROS). A monthly option is [http://www.power2people.org/funds/aros/ here].


Future goals for AROS include expanding its underlying retargetability to support even more diverse architectures, provide memory protection features and user level file security, SMP and many other wonderful features missing from AmigaOS &amp;mdash; while still providing as much source level compatibility as is possible (however it is accepted that to achieve some goals code certain things may require a little recoding).


[http://www.ohloh.net/p/aros/contributors Developers] come and go as with any open source effort and we would like to thank them for their efforts... 

;1996-2000:In DigullaA (coordinator), GripJ, TempletonI (BSD), SchulzM, RittauS, voordenDagL, HolmM, JohanssonT, VanIngelgomH, SteigerwaldM, BortasP, deJongK, AlfredssonJ, InnocentiB, 

;2001-2005:In [http://chodorowski.com/adam/aros.html ChodorowskiA], StegerG, BergerS, HeutlingS, AlemagnaF (gcc), VerhaegenS (rexx), KielH, MatheussenKS (CAMD), SzczygielskiP, ErikssonP, LeCorfecD (Zune), BauerS (Zune), FurlongW, GustafssonJ, AndrewsN, CafferkeyN, GierichM (jpeg), PattonJ, ParsonsM, DietrichJ, SeilerT, BischoffL, LorentzenNH, AdamO, BerglundH, SmithP, HolmenD, BlomM, 

;2006-2010:In FedinP, RusslerM, SzymczykS (owb), SmiechowiczK (openGL), WeissM, NorrisR, BrunnerO, WiszkowskiT, GreppinA, [http://www.fukt.bsnet.se/~bearsoft/ Bearsoft Björn Screwelius], ErbY, CharletF, HodgesC, [http://aros-exec.org/modules/newbb/viewtopic.php?topic_id=4819&amp;forum=18&amp;post_id=43103#forumpost43103 HokstadV], McMullanJ (m68k), WilenT (m68k), 

;2011- :In MuijzenbergPHvanden, ALB42, JonesEM, weiju, DizzyofCRN, wawa, miker, 


* 1996 - The linux hosted version for i386 was the first to arrive 
* 1998 - i386, The native version for i386-based PC AT computers and compatibles.
* 2004 - x86/64, The native version for 64-bit (x86_64, amd64) PC computers.
* 2008 - sam440/ppc, The native version for Sam440EP, Sam440EP Flex and Sam460ex computers.
* 2009 - efika, The native version for PowerPC Efika computers.
* 2010 - m68k, The native version for m68k Amigas or WinUAE
* 2013 - raspi/armfh, early native version for ARMv6 based Raspberry Pi computers.
* 2017 - x86/64bit smp 


Debugging capture serial debug at all (especially with sysdebug=all or --sysdebug=all) to see it displayed on screen 

* yes, usb -&gt; rs232 adapters can work most of the time, some of the cheapest ones are not fully compatible with all rs232 devices to capture to another device 
* you will need a null modem cable (or a null modem adapter usually female to female) in addition to the usb -&gt; rs232 adapter (usb adapter is a normal modem ie. the pins are not crossed over) 

Normal modem cable - straight connection DCE 
&lt;pre&gt;
Pin 2 -&gt; Pin 2  RXD
Pin 3 -&gt; Pin 3  TXD 
Pin 5 -&gt; Pin 5  GND
&lt;/pre&gt;

Null modem cable connections DTE 
&lt;pre&gt;
Pin 2 -&gt; Pin 3
Pin 3 -&gt; Pin 2
Pin 5 -&gt; Pin 5
&lt;/pre&gt;
(9pole SUB-D)


&lt;pre&gt;
serial  ser: (amiga/aros)  tty2 tty1USB0 (linux)  COM1 (windows)  (depends on the os being used) 
speed baud transfer rate 9600 38400     lower baud might be more successful 
data bits 8
stop bits 1
parity none
handshaking flow control - none xon/xoff (most likely)  rts/cts  dsr/dtr (pins not connected so should not work) 
&lt;/pre&gt;


*You cannot use compiled aros X86-64 bit software (when ready) on aros X86 32bit. PPC compiled software on X86 and so on. 
*68k is tested with the UAE emulator (WinUAE) but some tests are done on native 68000 based Amigas and others. 
*PPC support is very limited to certain devices. 


If you use the WBStartup, you have to delete the other icons in the folder (readme etc..) and you have to add in the Icon Tooltype the parameter DONOTWAIT

If you use user-startup instead, you need to add the attached command &quot;after assignment to LUA&quot;
C:WBRun DH1:Extras/Utility/WeatherBar/WeatherBar &gt;NIL:
Change the command to match your WeatherBar path.

&lt;pre&gt;
PATH sys:Utilities/WeatherBar ADD
run &gt;nil: lua:amilua weatherforecast.lua
&lt;/pre&gt;

To enter data your Country or City, ist with city_id numbers can be found [http://bulk.openweathermap.org/sample/city.list.json.gz here] or you need to go to [https://www.bbc.com/weather BBC Weather], once you type the name of your city or town in the appropriate tab, and press enter, the 7 numbers to be added in the &quot;WeatherBar&quot; will appear on the Browser url address bar above 


Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251 – Cyrillic (Amiga)
    ISO-8859-1 – Western European
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2 – Central/East European
    ISO-8859-3 – South European
    ISO-8859-4 – North European
    ISO-8859-5 – Slavic languages
    ISO-8859-9 – Turkish
    ISO-8859-15 – West European II
    ISO-8859-16 – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)
&lt;/pre&gt;


Icaros 2.3 USB image needs a header stripped so it can work correctly 
 dd bs=512 skip=1 status=progress if=icaros_light_2-3-0_pendrive.bin of=/dev/sdxy &amp;&amp; sync


Scalos 
&lt;pre&gt;
-------------------------------
{ &quot;STRING&quot;,		&quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;,

HALIGN		LEFT | CENTER | RIGHT

VALIGN		TOP | CENTER | BOTTOM

STYLE		NORMAL | BOLD | ITALIC | BOLDITALIC

FONT		// font specification - format: &quot;fontname.font/size&quot;

-------------------------------
arguments for STRING SRC

&quot;diskstate&quot;,		
&quot;diskusage&quot;,		
&quot;diskusagefree&quot;,	
&quot;diskusageinuse&quot;,	
&quot;diskusagepercent&quot;,	
&quot;fibfilename&quot;,	
&quot;filecomment&quot;,	
&quot;filedate&quot;,		
&quot;fileprotection&quot;,	
&quot;filesize&quot;,		
&quot;filetime&quot;,		
&quot;filetypestring&quot;,	
&quot;iconname&quot;,		
&quot;linktarget&quot;,		
&quot;plugin&quot;	pluginname &lt;optional plugin arguments&gt;
&quot;versionstring&quot;,	
&quot;volumecreateddate&quot;,	
&quot;volumecreatedtime&quot;,	
&quot;volumeordevicename&quot;,	

-------------------------------

arguments for HIDE

&quot;novolumenode&quot;,	
&quot;isempty&quot; (some STRING)	

-------------------------------

all internal commands:

&quot;about&quot;,		
&quot;backdrop&quot;,		
&quot;cleanup&quot;,		
&quot;cleanupbyname&quot;,	
&quot;cleanupbydate&quot;,	
&quot;cleanupbysize&quot;,	
&quot;cleanupbytype&quot;,	
&quot;clearselection&quot;,	
&quot;clone&quot;,		
&quot;close&quot;,		
&quot;copy&quot;,		
&quot;cut&quot;,		
&quot;delete&quot;,		
&quot;emptytrashcan&quot;,	
&quot;executecommand&quot;,	
&quot;formatdisk&quot;,		
&quot;iconify&quot;,		
&quot;iconinfo&quot;,		
&quot;lastmsg&quot;,		
&quot;leaveout&quot;,		
&quot;makedir&quot;,		
&quot;open&quot;,		
&quot;parent&quot;,		
&quot;paste&quot;,		
&quot;putaway&quot;,		
&quot;quit&quot;,		
&quot;redraw&quot;,		
&quot;redrawall&quot;,		
&quot;rename&quot;,		
&quot;reset&quot;,		
&quot;selectall&quot;,		
&quot;showallfiles&quot;,	
&quot;showonlyicons&quot;,	
&quot;shutdown&quot;,		
&quot;sizetofit&quot;,		
&quot;snapshot&quot;,		
&quot;snapshotall&quot;,	
&quot;snapshotwindow&quot;,	
&quot;unsnapshot&quot;,		
&quot;update&quot;,		
&quot;updateall&quot;,		
&quot;viewbydate&quot;,		
&quot;viewbyicon&quot;,		
&quot;viewbysize&quot;,		
&quot;viewbytype&quot;,		
&quot;viewbytext&quot;,		
&lt;/pre&gt;


{{status|50%}}
{{BookCat}}</text>
      <sha1>ej47wj00qh2qebzd50avj54hioqfnn2</sha1>
    </revision>
    <revision>
      <id>4669851</id>
      <parentid>4669849</parentid>
      <timestamp>2026-09-13T07:50:22Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669851</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="138215" sha1="4049m7avrdihn4o2tj84x93251nkstk" xml:space="preserve">{{ArosNav}}

==What is AROS==

Google translation 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=nl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Dutch], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Italian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=da&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Danish], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Polish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ja&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Japanese], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ko&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Korean], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FUser%2FDocs Portuguese], 


*Computer Hardware
*AROS (operating system)
*Applications and Games
*User


[http://www.osnews.com/story/15819 AROS] is one of the intermediate levels between the computer hardware and the user. It is an open-source, clean-room implementation of AmigaOS 3.x that can be run on many different computer architectures. It runs primarily on PC x86 32bit and 64bit but also on amiga motorola 68k and compatibles, some ARM like the Pi and Apple Silicon, RISC-V and some old PowerPC. 

This page will cover enough to be able to write the downloaded image to your preferred media, to run a LiveUSB, LiveCD or LiveDVD on your office/home PC (Live meaning you can test without changing your existing setup) and, ultimately, to use it.  

Intel / AMD PC hardware support mostly covers the years 2000 to 2024. At the moment, AROS is '''not''' recommended to be '''installed''' on a working vital data holding machine. Instead, writing to and booting from a '''USB stick''' could be a much better option. 

AROS is an hobby OS and can co-exist with Windows(TM), MacOSX(TM), Android(TM) or Linux(TM) and act as an alternative. 
Unfortunately, Aros has few developers so upgrades and improvements can take [https://sourceforge.net/p/aros/mailman/aros-cvs/ time to appear]. 

AROS core is now [http://en.wikibooks.org/wiki/Aros/Developer/IncompleteAPIs ~80%] finished and is usable, so keep in mind that the software is still considered ALPHA/BETA and in constant development. Currently AROS is fun to play with on a curiosity level, but it is also interesting to program. AROS has some multimedia features and has internet access.  

Most importantly, use AROS to its maximum potential as it stands now, find ways to have fun with it and share your experiences. 


Good Sites to visit 

: [https://www.arosworld.org/home.php Aros World User forum] 
: [https://arosnews.github.io/ AROS News]
: [https://www.facebook.com/ArosWorkshop/ Aros Workshop], 
: [https://www.osnews.com/topic/amiga-aros/ OSNews] 
: [https://www.reddit.com/r/aros/ Reddit]


: [https://archives.arosworld.org Aros Archives] 
: [https://aminet.net/ Aminet]
: [http://www.amiga-news.de/en/ English translation of German site]


: [https://aros.sourceforge.io AROS] with [https://aros.sourceforge.io/download.html ABIv1 downloads] 
: [https://github.com/aros-development-team/AROS Aros ABIv1 Codebase]
: [https://github.com/aros-development-team/AROS/issues register ABIv1 issues] and [https://sourceforge.net/p/aros/bugs/ old defunct bugs notification site] 


: [https://sites.google.com/view/arosone Aros One x86, x64] 
: [https://tinyarosdistro.flazio.com/ Tiny Aros x86 and x64]
: [https://arosnews.github.io/aros-portable/ AROS portable USB3 stick images of hosted Aros One x86 and x64 on debian] 
: [http://vmwaros.blogspot.com Icaros Desktop x86 now on sabbatical, very old edition] 
: [https://sites.google.com/site/arosaspireone AspireOS, of the netbook Aspire One, very old edition] 
: [https://github.com/deadwood2 Deadwood's builds], [https://www.axrt.org/download/aros/v11/ v11 64bit PC builds], [https://axrt.org/downloads-aros Updated i386 32bit PC builds], 
: [https://github.com/ezrec Ezrec x86 m68k mirror of old svn version]


: [http://arosalive.blogspot.co.uk/p/10-basic-aros-how-tos-tutorials.html Basic How To guides] 
: [http://arosgamer.blogspot.co.uk/ AROS Playground], [http://thewetmachine.net/tag/aros/ Jess Wet Machine], [https://aroshacking.wordpress.com/ Jon Robertson's AROS Experiences and FPC Free Pascal], [], 
:[http://www.apollo-accelerators.com/ Apollo Accelerators m68k], [http://www.amigablogs.net/ Amiga Blogs], [http://blog.a-eon.biz/blog/ Trevor Dickinson blog], 


: [https://forum.amiga.org/ Amiga OS AOS 3.x forum] 
: [http://eab.abime.net/ EAB Amiga] 
: [http://www.amigaworld.net/ AmigaWorld] 
: [http://www.ppa.pl/ Polish Amiga Like News] 
: [http://www.apollo-core.com/ Apollo Forum] 
: [https://amigaalive.blogspot.com/ AmigaAlive]
: [https://www.amigalove.com/software Disk Mags]
: [https://amigachristmastree.ultimateamiga.com/ Xmas Amiga Game Jam]
: [https://www.reddit.com/r/amiga/ Amiga]


== Distributions aka Distros ==

For end users there are distributions (ready made with selected apps aiming to be easy to use), mostly created and maintained by one person in their own workflow/style. They reuse the nightly boot compiles to suit their needs and possibly other end users. You are free to create your own if required. 

* For native 64bit Intel/AMD: [https://sites.google.com/view/arosone Aros One x64], [https://tinyarosdistro.flazio.com/ Tiny Aros],
* For native 32bit Intel/AMD which will run on 64bit machines: [https://sites.google.com/view/arosone Aros One x86], [https://www.tinyaros.it/ Tiny Aros], 
* For native 68k [https://sites.google.com/view/arosone Aros One m68k], [http://www.aros-platform.de/ AROS Vision], 

'''Please, keep in mind that the distros listed above use a different ABI (abi v11) , which is NOT binary compatible with the official ABI V1.'''
* For hosted Linux usb drive image [https://arosnews.github.io/aros-portable/ x64 Debian hosted version of Aros One], 
* For hosted ARM there is [https://github.com/jonx/AROS-AArch64/releases alpha for Apple Silicon] and [https://aros.sourceforge.io/nightly1.html RaspberryPi 3 raspi-aarch64-system native 64bit] 


AROS was originally developed on Linux but can run on an Intel-based Linux distro as an app. As time has gone on, it can be run as an app on many more operating systems (Windows, FreeBSD, Linux and limited on MacOS). This may sound strange: an OS running on top of another OS. 
Basically, this is to take advantage of drivers (audio, internet, graphics, etc.) and compiler environments, in the existing OS, with which people may be already familiar. The term we use for what AROS does is &quot;Hosted&quot;. 

AROS Native is the term coined to describe AROS being run without any OS underneath it. It runs alone just like AmigaOS(TM) did. As this version does not benefit from &quot;Hosted&quot; drivers, dedicated ones have to be ported/written. Hence the smaller range of supported hardware / peripherals. We have other pages highlighting this support 


AROS is open source so basically everyone can take part. The source is public on github and there are new commits most days. AROS is automatically compiled daily, result are the nightly builds hosted on Sourceforge. The nightly builds are only used for testing changes, testing software and the starting point for distribution maintainers or even your own distribution. They are very basic, miss some functionality and apps like web browsers and generic general appearance which can be changed. 

* The [https://sourceforge.net/projects/aros/files/nightly2/ Nightly2], [http://aros.sourceforge.net/download.php nightly builds File Release Service] or [http://aros.sourceforge.net/downloads/ Sourceforge Project Web builds] are made automatically every night directly from the Github and in the past, SVN (Subversion) tree and contain the latest code for the AROS operating system. It should be noted that the builds have not been tested in any way and can be horrible broken. 

*ABIv11 offspring of 64bit PC ABIv1 i.e. another PC 64bit build 
*ABIv1 standard for most nightly builds, it is where the most work is done by developers 
*ABIv0 standard for PC 32bit intel / amd PC distributions for historic reasons 


==Media==

AROS media tends to boot in this tier list of media types, first internal HDD SSD, CD DVD drive, and finally usb drive (last two can depend on bios boot order) 

* USB .VHD 

[https://sites.google.com/view/arosone Aros One x86 and x64], with md5 below 

&lt;pre&gt;
0a656d53a9c902e9934000d8392e30ec *ArosOne-USB-1.3-64Bit.zip
7dd7119ab3e56d75ee852c137226b4d7 *ArosOne-USB-v1.2-x86_64-v11.zip
cf906eeaad4a83b3520b1896bdc6b0d3 *ArosOne-USB-v1.1-x86_64-v11.zip

e2eb8fe8cfd61c567b0152a61cf85251 *ArosOne-x86-v2.8-USB-IMG.zip
559909c75c2f56472c74267a7d075355 *ArosOne-x86-v2.7-USB-IMG.zip
93da5898508c1a8c05bb8991ab7bd117 *AROS One Image-USB-2.4.zip
59fcabd7090e47f12d54f7eb78cf0f45 *ArosOne-x86-v2.2-USB-Image.zip
24fb8de726ae8fc5fe5bac6d30f03dc5  ArosOne-x86-v2.0-USB-Image.zip
f3d725e990072edce633b59747911b6b  ArosOne-x86-v1.8-USB-IMG.zip
e089a24ae310e92fcc407a0125602ce8  Aros-One x86-IMG-USB-v1.6.zip
&lt;/pre&gt; 


[https://tinyaros.flazio.com/ Tiny AROS]

22bc993625b7c75b17263c0cc7e7baaa *Tiny Aros_copy.vhd (March 2024) 


There is usually a vhd image inside the zip that can be written to USB sticks which is so much faster than the old ISO written to physical CD DVD method. This .vhd can be written to an USB stick / ssd with these pieces of software below but it will erase the previous contents from the usb 

Windows - [https://www.raspberrypi.com/software/ RPi Raspberry Imager, use custom and see all files], [https://hddguru.com/software/HDD-Raw-Copy-Tool/ HDD-Raw-Copy-Tool], [https://rufus.ie/ Rufus up to version 3.20 may work with VirtualBox HD vhd images with Win7 but not some Rufus 4.x versions], [https://etcher.balena.io/ Balena Etcher but may spy on you], 

Linux   - [https://www.raspberrypi.com/software/ Raspberry Imager Ubuntu], Suse Image / Multi writer, dd, 

Mac     - 


* Virtual Machine .ISO or CDs DVDs 

 The native iso images are currently not compatible with Ventoy, Yumi, MultiBootUSB, Easy2Boot E2B, or similar 

&lt;pre&gt;
617a905b1665128c5e05f94dcc48e7f1 *AROS-One-v1.3-64Bit-v11.zip
11c8a147fcad7ecf52ae3a43e1934b69 *ArosOne-DVD-v1.2-x86_64-v11.zip
f93053d3b9ccf304d7e6ac3389e1987b *ArosOne-DVD-v1.1-x86_64-v11.zip

86d808a40dc7be389a758799a9b4f595 *ArosOne-x86-v2.0-ISO-DVD.zip
f1fc8599ef6a39e5df394e0f41d55526 *AROS-One-x86-ISO-DVD-v1.6.zip
&lt;/pre&gt;


You can use a virtual emulator like VirtualBox, VMWare to mount the iso image which can then be used to boot and/or install to USB. 

No current software can write an AROS ISO to a Pendrive. The author of ‘Rufus’ (who used an Amiga 500 as a child) once tried, but when he saw the system composition, he said he was unable to do it.

The solution is to boot the ISO from a VM (WMware, VBox), then install the AROS build on the Pendrive, which will eventually become a Live Pendrive that can be booted on a PC.

The only precaution is that in some cases it is necessary to thoroughly clean the Pendrive of any partitions and remove any bootloader that is not AROS. The Pendrive must remain raw without any partitions.

You can clean the USB stick on a PC with a program that manages hard disks. You need to do a partition wipe. On some USB sticks, you can clean it with InstallAROS.
For some USB pendrives, please use a reputable partition editor to remove any and all partitions from a usb pendrive as HDToolbox cannot do this task sometimes with a wipe all option. 


Previously the only installation option was CD-RW or DVD-RW, since the whole system can be burnt onto a single disk and can be reused when the next version is released. Good branded discs like Taiyo Yuden (later JVC) or Verbatim should be used to reduce frustration later. The days for this media is gone but kept here for information 

Since nobody currently sells AROS on any other media, you will need access to a CD/DVD burner to create the installation disk yourself. After it is on a CD or DVD, then access and writing to USB pendrives becomes available (this should be viewed as an outdated or last resort alternative method now), as well as using good USB manufacturers like Sandisk, Kingston, etc. rather than some other no-names. 

Try burning it to a CD-RW or DVD-RW using your CD/DVD burning program (most burning software have a burn iso option). The ideal writing speed is 2x or 4x, higher speeds can give errors and problems.  Check the writing integrity of your CD or DVD if your software has an option to do so before going any further. 

Standalone portable usb cd dvd drives do not boot physical burnt discs, please use an internal ide sata drive instead. 


* SD-card
For [https://aros.sourceforge.io/nightly1.html ARM Pi Aros 64bit], copy the files onto a FAT32 formatted micro SD card. 


==Booting==

The LiveUSB, and in the past LiveCD LiveDVD, is designed to trial (test drive) various operating systems without having to install them to your working system. 

Since 2011, UEFI was introduced to replace the original PC BIOS which made booting media more confusing. Some changes in the UEFI/bios may be needed 

*go into the bios using esc, f2 or f? and disable the Security -&gt; Secure Boot and maybe apply option for Legacy IDE mode 
*you may have to press F9, F10 or F12 or p on boot up to present a device boot options like USB or CD/DVD 
*disable the Fast Boot config so it would recognize portable DVD-drive and changed the Boot-sequence

Secure boot was introduced by Microsoft and later consortium, control what operating systems work with Secure Boot via shims. 
For Aros, it is best to disable and save the turn off change to Secure Boot (if you dual boot with Windows this will cause issues with further Window boots) 

 For the best experience, it is advised to install to another SSD than the one Windows resides on. 

The grub part of the boot should be fully automatic, and you should see a multiple choice graphic card screen after 10 seconds for USB or 40 seconds CDs and DVDs. 
If boot does not occur within a minute, please reboot and choose the VGA boot option as it relays a message stream so you can see where the issue lies. 

After the grub graphics choice, AROS takes over the booting and any issues can arise here 

If possible please use a branded usb pen drive as most of the time when we get reports of &quot;crashes right after grub boot selection&quot; it is mostly due to the recorded pendrive as they are made, notoriously on a will it work / will it fail nature, every time it is used. 
&lt;pre&gt;
So one usb drive written may stop at a System halted. Reset the machine. 
Or another pendrive will show give errors Smart Filesystem request - Volume 'Aros Live Drive' (DU0: usbscsi.device unit 0) There was an error while accessing this volume: 
Or if a FAT32 partition present - FAT filesystem - Device USBSCSI0P1 has a read error on block xxxxxxxx - 
&lt;/pre&gt;
Sadly, no drive even branded are resistant or totally reliable, so the only solution is to try another pendrive, and possibly to repeat, until no errors. 
It will give an indication on how reliable the usb drive could be. 


=====Advice for various machines=====

Some of the stages involved and shown on the display in a typical AROS boot start up 

&lt;pre&gt;
[MultiLoader]
[ELF Loader]
[Boot]

[HPET] 
[Kernel:ACPI]
[Kernel:APIC-IA32]
[Kernel:SMP APIC]
[HiddStorage]

ACPI: ????
ACPI Error 
[ACPI]AcpiOs????
[BattClock] Got RTC century offset 0x32 from ACPI 

[PCI] Scanning bus ? 
[AHCI] Sata 
[Vesa]  only if vesa is chosen as graphics option 

[ATA] detect hd &amp; cd drives 
[ATA0?] ata-identity 
[packet] fat.handler be.handler, etc. 
[DOS] 
[Storage:Bus]
[Storage:Controller]

[MSS] USB setup
[ehciInit] Port ? maps to controller ? 

[I2C] 
[ATI]
[drm] nouveau 
[AROSTCP]   if you have network driver prefs set up to start when booting 


&lt;/pre&gt;

; If boot fails, please give us some indication (pictures or videos) where the boot stops and the message(s) on screen. 


AROS's native SATA/AHCI driver doesn't always work. If you get errors related to ahci.device, try disabling it. At your chosen boot entry in the GRUB menu, Press E, scroll down to the ahci.device entry, and add a # or ; at the start of that line or delete it with Ctrl-K. Then press Ctrl-X or F10 to boot. 

If your disk isn't accessible at all with this change, you might need to change the SATA controller to IDE legacy mode in the BIOS: however, making this change will likely cause problems booting Windows on the same machine (if it's already installed). To disable ahci.device permanently, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and remove the ahci.device line from all boot entries you intend to use.

SATA AHCI Timeout while waiting for device to complete operations with BIOS SATA entry set to AHCI mode stops at &quot;waiting for bootable media&quot; screen, changing BIOS SATA setting back to IDE mode may allow it to continue booting 

The ATA driver doesn't always work. If you get errors related to ata.device, try using the alternative in sys:devs/alt which is an older version.  Press E when your chosen boot entry is highlighted in the GRUB menu, scroll down to the ata.device entry, and change it to read &quot;module /Devs/Alt/ata.device&quot;. Then press Ctrl-X to boot. To make this change permanent, edit the text file &quot;SYS:Arch/pc/grub/grub.cfg&quot;, and change the path to ata.device in all boot entries you intend to use.


Further options (removing the &quot; &quot;) to add to the GRUB menus to disable certain other components for debugging:

&lt;pre&gt;
Disable AHCI                        &quot;AHCI=disable&quot;
Disable NVME                        &quot;NVME=disable&quot;

Disable ATA:                        &quot;ATA=disable&quot;
Disable ATA:                        &quot;ATA=nopci,nolegacy&quot;
ATA safe mode:                      &quot;ATA=nodma,32bit&quot;
Disable IDE from SATA:              &quot;ATA=32bit,nosata2pata&quot;
VIA / SIS with cdrom read io errors &quot;ATA=nodma,nopoll&quot; 

noacpi                   all [PCI] devices to be invisible to AROS. disk drives work but network, sound won't 
acpi=strict              if there are issues with sound after boot 

noioapic                 alternative to no acpi 

Set AHCI                            &quot;AHCI=force150/force300/force600&quot;
Disable AHCI/SATA:       comment out with a # ; or remove ahci.device line with Ctrl-K

Disable USB:             comment out # ; or remove pciusb.device and poseidon.library lines with Ctrl-K
Disable native graphics: &quot;nomonitors&quot;
USB3                     &quot;USB=xhci&quot; 
&lt;/pre&gt; 

Other useful grub command line options - nomonitors, noacpi, vesahack, nopoll 

Press Ctrl and X together (or F10) to exit and boot with the new options. Just experiment with different variations until successful. Those working options will need to be reused with every reboot of AROS until you can edit the grub.cfg and make it permanent i.e. install to hard disk or USB. 


* If you use VESA mode, you can see the debug log if you add 'vesahack' to the command  line.  This  will set up split-screen mode. In the upper half you'll see AROS screen, in the bottom - debug log. 
* ACPI ie. PCI hardware - If  you  get  crashes  at  early boot, try adding 'NOACPI' to the command line 


If you're having boot issues and have a null modem cable and a spare pc, a boot log is always useful. Edit your grub line to include debug=serial but would try with an with sysdebug=all in the line later as it can cause issues booting on machines with sysdebug=all enabled (corrupts the cpu initialization). 

However, if you feel you have found a genuine bug/fault in AROS that needs attention, please use the [http://sourceforge.net/tracker/?atid=439463&amp;group_id=43586&amp;func=browse bug submission form] to record as much information about what happened, why, and what hardware etc. you have so that people may try to assist you 


For Virtual machines VMWare VirtualBox, etc., attach and press play to start the ISO image 

If booting hasn't worked then it could be down to Bios/UEFI settings  


=====nvme.device=====

 Since 2018, nvme drives are standard on most machines 

The requirement is that a PC can boot with legacy mode/BIOS at the moment - Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

 This is still in testing and its' use should not be on or near precious own data 


=====AHCI=====

 Starting taking over since 2011 on a lot of machines 

* Check that UEFI (replacement for PC BIOS) has options set to remove UEFI SecureBoot option and apply CSM 
* SATA drive is set for Legacy or a mixture AHCI/IDE and not AHCI 


 AHCI sata can be very difficult to get working

Most Windows installs are already set to AHCI sata, changing this to a legacy IDE mode setting can help but please check if Windows will still boot. Some hardware like Lenovo laptops do not always like being set in legacy mode so only use as a last resort and aware of issues that can be caused. 

Now as far as hardware goes on a newer machine with an NVME drive you may need to add NVME=disable as the NVME driver could potentially cause lockups. 

With a 16C/32T chip machine, disable SMT and it should boot. 


=====ata.device for old BIOS's =====

 Pre 2010 this was the de facto standard method of providing settings to the computer at a lower level 

Some adjustments to the BIOS setup options are necessary (usually by pressing a key like DEL, F1, F2, F12 or ESC, p on the very early boot up of the computer). 

*Adjust booting options like moving USB hdd, CDROM higher as it is quite often disabled or placed lower by default, i.e. USB hdd, CD/DVD are placed at the top above the hard drive. Try looking here [http://www.windowsreinstall.com/articles/bios/ Windows] or [http://www.hiren.info/pages/bios-boot-cdrom Bios] or [http://www.wikihow.com/Set-Bios-to-Boot-from-a-CD-ROM Boot] or web search &quot;BIOS BOOT CDROM&quot;

* At the '''SAME''' time, check if the SATA/AHCI option is set to Emulate or IDE Legacy, though this can have '''issues''' with any OS already on the hard disk. If in doubt, do nothing and seek advice. 

* check that under BIOS settings you '''DO NOT''' have plug&amp;play OS selected as Aros at this point is unable to route interrupts on its own and needs the BIOS to do that. 

'''Save''' options changed at the end. 

PCITool can show if the motherboard chipset is in IDE mode. 
Class = 0x01 means STORAGE, Subclass = 0x01 means IDE. Also ProductID 0x3a20 resolves to non-AHCI mode in Intel ICH10 documentation.


==Installing==

We have a separate section [https://en.wikibooks.org/wiki/Aros/Platforms/x86_installing here]

We have a specific section for each CPU platform under the Specific platforms in the NavBar navigation bar on the right hand side menu 

error code (-6) when using the ahci.device (has writing to disk problem but not reading) is enabled. change this line in your grub and reboot 

&lt;pre&gt;
#module /Devs/ahci.device      &lt;&lt; disable
module /Devs/Alt/ata.device    &lt;&lt; add this line instead
&lt;/pre&gt;


==File structure overview==

AROS' directory structure is mostly identical to AmigaOS directory structure, with some additions.

AROS: or SYS: also known as DH0: (i.e. the drive partition with AROS system) has the following simplified list of the main drawers (Amigas term for directories/folders). 


{| class=&quot;wikitable&quot;
|boot:
| grub bootloader 
|----
|C:
| small apps, where AROS looks first for applications/games but will look at Tools, System afterwards
|----
|Classes:
| .class 
|----
|Devs:
| .device .resource and in their own drawers (folders) .audio, .hidd, network, graphics 
|----
|L:
| where .handler files go 
|----
|Libs:
| where .library files go 
|----
|Prefs:
| applications that adjust or setup AROS functions and capabilities 
|----
|S:
| startup scripts (for the aros boot process '''not''' grub) are stored here
|----
|Storage:
| place to keep old or alternative device drivers
|----
|System:
| applications associated with AROS operating system
|----
|Tools:
| extra applications
|----
|Utilities:
| extra applications
|----
|WBStartup:
| copy applications here to autostart with needed icons, drawers, data etc
|----
|}

See [[Aros/User/DOS#Drives.2C_Files.2C_Assigns.2C_Directories|DOS manual: Drives, Files, Assigns, Directories]]


=== Filesystem ===

Whilst the kernel is the heart, the filesystem is the blood of the system they are split into two categories (only a few are supported) 
&lt;pre&gt;
Journalling     - SFS PFS3 but also NTFS ZFS XFS ext4 
Non-journaling  - FFS FAT32(VFAT) but also exFAT BtrFS ext2  
&lt;/pre&gt;

Filesystem options for AROS to install 
* SFS default 
* Professional File System PFS3 [http://eab.abime.net/showthread.php?t=52234&amp;highlight=pfs3+free&amp;page=13 only on motorola 68k at the moment] 
* FFS very old now but left in for legacy usage 

Other [https://archives.arosworld.org/index.php?function=browse&amp;cat=driver/filesystem filesystems] for storage purposes 
* FAT32 favorite as most OSs support 
* NTFS (can lock AROS) 
* exFAT 

The only filesystems that really NEED defragging (i.e. disk tidy up) are from Microsoft(TM) - exFAT/VFAT/NTFS
*SFS tries to do exactly the same thing, but in certain cases it doesn't do as well as PFS. But you can defrag SFS 
*PFS *minimises* the amount of fragmentation, but does not automatically defrags as it saves files to the drive 

The setup of the below filesystems is usually done by the distro maintainer but if not....
&lt;pre&gt;
Copy L/exfat-handler L:

DOSDriver or Mountlist entry for an exFAT partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = exfat-handler
DosType        = 0x46415458
&lt;/pre&gt;

&lt;pre&gt;
Copy L/ntfs3g-handler L:

DOSDriver or Mountlist entry for an NTFS partition make sure that the FileSystem and Handler are set as follows:

FileSystem     = ntfs3g-handler
DosType        = 0x4e544653

Also to make a read-only mount you can set:

Control        = ro
&lt;/pre&gt;


The Smart File System (SFS) is a journaling filesystem used on Amiga computers and AmigaOS-derived operating systems. It is designed for performance, scalability and integrity, offering improvements over standard Amiga filesystems as well as some special or unique features.  

SFS is written in C and was originally created and released as freeware in 1998 by John Hendrikx. After the original author left the Amiga scene in 2000, the source code to SFS was released and its development continued by Ralph Schmidt in MorphOS. 

Its development has now forked; as well as the original Amiga version, there are now versions for MorphOS, AROS, AmigaOS 3, and a version for AmigaOS 4, which have different feature sets but remain compatible to each other.  Versions for AROS, AmigaOS and MorphOS are based on different branches.  

In addition, there is a driver for Linux to read Amiga SFS volumes, GRUB natively supports it and there are free drivers to use it from UEFI.  The Linux version is [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ independent code].  

SFS (Smart File System) partially defragments itself while the filesystem is in use. The defragmentation process is almost completely stateless 

AROS SFS version has a 120GB partition size limit on hard disks and DVDs current 4gig size limit. 
The sources for the MorphOS 64-bit version of SFS were available but no porting to AROS has happened so far due to endian issues, etc. 

SFS Tools 
* GUI - arSFSDoctor, 
* CLI - sfscheck , [http://www.portacall.org/ sfsundelete], sfsformat, setcache hits a usability ceiling around the 10GB / 100,000 file mark, 

 sfscheck dh0: seek purge fraglist defragment

If there are two simultaneous file writes in progress and you reboot machine (or it locks up or crashes) you may end up with a corrupted filesystem. Although arSFSDoctor may help, you might have to copy the files to another partition, format the partition with the errors on and copy the files back. 


PFS / SFS are way more advanced and much much faster than the FFS. FFS is supported for legacy reasons only. 
The Professional File System (PFS) is a filesystem originally developed commercially for the Amiga and now distributed on Aminet with a 4-clause BSD license. It is a compatible successor of AmiFileSafe (AFS), with an emphasis on added reliability and speed compared to standard Amiga filesystems.  It also features multi-user abilities like the older MuFS. 

PFS has so many advantages including the important things, speed, the ability to recover all deleted files even simply same name by typing the command &quot;. Deldir&quot; convenient if done in Directory Opus, virtually deleted files are copied normally as if they had never been deleted, other convenience is to not ever invalidate the filesystem, just put it on top of the startup-sequence command &quot;diskvalid&quot;, which automatically corrects any irregularities in the system startup; PFS also provides a device for floppy which makes them very fast and takes advantage of the full capacity of the floppy including the area dedicated to the bootloader.

The device is split into two main areas. At the beginning of the device is the metadata section, which consists of a root block, and a generic array of blocks that can be allocated to store metadata. The rest of the device is another contiguous generic array of blocks that can be allocated to store data. The metadata section usually uses a few percent of the device, depending on the size of the device.

The metadata is stored as a tree of single blocks in the metadata section. The entire directory structure is recorded in the metadata, so the data section purely contains data from files. The metadata describes the location of data in files with extents of blocks, which makes the metadata quite compact.   

When a metadata update occurs, the system looks at the block containing the metadata to be changed, and copies it to a newly allocated block from the metadata section, with the change made, then it recursively changes the metadata in the block that points to that block in the same way. This way, eventually the root block needs to be changed, which causes the atomic metadata update.   

The filesystem is reasonably good at keeping files unfragmented, although there is a defragmentation tool available which will work on an online filesystem ie whilst being used. 

It was the first filesystem to introduce the concept of the Recycle Bin natively at filesystem-level to the Amiga, holding the last few deleted files in a hidden directory on the disk root.  

PFS version 5.3 was developed in C and a small portion of assembly code by Michiel Pelt.  There are endian issues to be overcome and adapting the small amount of m68k to C before use on intel based machines, etc.  


Autoupdate of files in a directory is already implemented in Wanderer, but not all file systems handle dos.library/StartNotify() in its full extent. It seems to work correctly in Ram Disk (thanks to AmberRAM handler), and it also works on SFS formatted devices. Other file systems might not yet have it implemented correctly though. 

The PC equivalent of the Amiga's RDB is the master boot record (MBR).


===Installing Applications===

The typical means to install applications under AROS/AmigaOS involves simply copying/extracting the archive (.zip .lha .rar .tar.gz) file containing the applications files to your own desired location i.e. drawer/folder. Once extracted, launching it by double clicking on an icon (recommended) or using the shell (alternative). Generally, this is on a separate partition from your AROS system files, however in reality it can be any location - including RAM: if you don't want it staying around too long especially when you switch off. 

At some time in the future it may be desirable for AROS to have a package-manager like subsystem able to retrieve information online about packages available for AROS and whether they update anything you currently have installed, however at the moment no such ability exists.


===User Data files===

AmigaOS has no notion of a default location to store user data files, and presently neither does AROS - though it may be desirable at some time to provide a common start location.

Some people, have extra small FAT32 partition(s) using HDToolbox, and not Qparted, to store data especially if a reinstall is ever needed. And then setup the usual Sys: (DH0:) and maybe Work: (DH1:) / Live USB (DU0:) and maybe Briefcase (DU1:) partitions. 


===User Environment configuration files===

AmigaOS/AROS stores persistent system configuration data in directory assigned to ENVARC:.  This, by default, points to SYS:Prefs/EnvArc.

During boot a copy is made to another assign, ENV:, which is for runtime usage.  Changes to the files here will not survive a reboot.

Setting the env variables is generally done by applications themselves, or when necessary by the user using the SetEnv command. SetEnv has a SAVE switch to force the persistent copy in ENVARC: to be written also for when you are sure the change should be permanent.

Under the standard installation of AmigaOS style OSs, ENVARC: is copied to ENV: upon startup, which, if you have a hard drive installation, is in RAM:, hence, ENV: ends up being RAM:Env.

ENVARC: is the Environment Archive, which is the permanent copy of ENV:, which is the Environment.  It's roughly like the Registry in Windoze. 

Most programs do (and all should) store their settings in ENVARC: somewhere, and load them from ENV:.  The effect of this can be seen in the Preference editors.  If you Save your preferences, they go in ENVARC: and ENV:.  If you click Use, they only go in ENV:.  If you reboot, normally, anything saved to ENV: is lost, and is replaced with a copy of what is in ENVARC:.

you can set the default public screen for any tool started from a cli with the PUBSCREEN variable. So open the pubscreen, set PUBSCREEN to the name and start newcli for example, then the new cli window (and all following windows opened from that window) will appear on that public screen.


===Drivers===

For certain hardware, e.g audio, networking and , there is no auto setup. Just like the original Amiga OS. 
For audio, use AHI in the Prefs folder to set Music and at least Unit 0 with the appropriate driver and press Save. For ethernet and wifi, please use SYS:Prefs/Network 

All hardware support is placed in the Devs drawer (folder/directory). The network drivers &lt;something.device&gt; go in the Networks sub-drawer. Audio drivers &lt;something.audio&gt; are put in the AHI sub-drawer. Graphics drivers &lt;something.hidd&gt; are put in the Drivers sub-drawer. 


==Configuring==

AROS has mainly decided on a MUI-like requester&amp;menu clone called Zune so changing the background, icons, font, menus can be done with SYS:Prefs/Zune 

AROS has several desktop GUI front ends like 
* DOpus5 Magellan II, Wanderer and Scalos (medium) 
* AROS Workbench, Workbook (smaller) 

File / Directory managers like Dopus4, MCAmiga, 

App Launch Shortcuts like FKey, BoingIconBar, right mouse click on magellan, wanderer desktop, Amistart, etc. 

General usability decisions - Prefs/IControl, Prefs/Locale, Prefs/Input, Prefs/Fonts, 


Select an icon with left mouse button and then right click the mouse button and selecting Icon -&gt; Information gains access to the tooltypes tab where information can be edited 

CLI in icon's tooltypes means 'run it as if it was run from shell'
If, on the other hand, the WB parameter (or no parameter) is present in Tooltypes, Wanderer will execute the binary and, if provided, the options included in Tooltypes. 

WBxCLI is very useful for adding options to DOS Commands.

Important: AROS has a different way of managing icons. If you have an executable file, you will never be able to add a project icon. AROS will automatically recognise that it is an executable file and will transform the icon into a tool icon.


Icons are typically now .png pictures renamed as .info e.g. so Office application name would have a Office.png renamed as Office.info or MyApp.png as MyApp.info, etc.  

Leave Out menu option to leave app icon on desktop 

To select multiple icons and save their positions, click on the first icon and after while you hold the Shift key down select further icons and don't release it before SnapShot is finished.  You can also select a whole group of icons by pressing the LMB at the top left of the icons and while keeping the LMB down moving the power towards the bottom right. A expanding bounding box will appear and all the icons within it will be selected.  

Clean Up menu option (right mouse button -&gt; Icons) rearranges icons in a drawer or disk window into a neater condition. To use, open the window to rearrange and select Clean Up. To keep the icons in the new positions, select all the icons (shift key or mouse selection) and select 'Snapshot' and then Window and then again with All.  

In DOpus5, Scalos, wanderer, most files have an icon file associated with it. To change the default tool, select Icon menu, Information, and change the default tool string. For example, you could use Multiview, Editor and so on for most text, graphics and some sound files as long as the appropriate Datatype classes are installed. For scripts, set the tool to C:IconX 


We have new Icon edit tools in progress but if you need to...
 C:Join Image1.png Image2.png TO MyFile.info
is enough to make a dual state icon from two png images. You can then use Wanderer's menu Icon/Information on it to edit its fields and tooltypes.

[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/icon AISS toolbar images] unpack unarc them into RAM: and copy Images directory to SYS:Prefs/Presets/  AISS icons are looked for in PROGDIR:, PROGDIR:Images, SYS:Prefs/Presets/Images and then in TBImages: according to Open Amiga guidelines.  

there is Demos/iconscale which could be launched from S:User-Startup with two arguments, telling it the horizontal and vertical size. IE something like 
 Demos/iconscale 40 40
It will shrink icons... not sure if it will be very nice though. it doesn't work for the icons on the main desktop. 

there is an option to scale an icon to a bounding box afair, try iconsize followed by two numbers, like:
 iconsize 32 32

Is there any way in AROS to change an icon type from Project to Tool or vice versa?
Either the SIT option of [ ProcessIcon], or the TYPE option of HandleInfo (not sure if this one works at all, please test with care).
 processicon sys:pathoftheicon SIT=Project 

SIT Set type of ICON. Allowed types are: &quot;Disk&quot;, &quot;Drawer&quot;, &quot;Tool&quot;,  &quot;Project&quot;, &quot;Garbage&quot;, &quot;Device&quot;, &quot;Kick&quot; and &quot;AppIcon&quot;.

Btw, are your icons, the #?.info files, writable, is the W flag set ?


'''Decoration''' is Aros' way to provides a way to hide the old Workbench 3.1 style of windows and screens. In Prefs/Appearance some decorative theming elements need work 

Themes - SYS:Prefs -&gt; Appearance 
The default content of Prefs/Env-Archive/SYS/themes.var should be &quot;themes:ice&quot; but can be changed via the Appearance prefs, please do NOT click the Use button. Its useless. As you know, it will ask for the theme volume. Just pick the theme you want, click on Save, then reboot. 

* Decoration is on. Any time trying to change theme, you get: &quot;Please insert volume Theme: in any drive&quot;? 
You could check if you find SYS:System/Themes or if it is missing. Then you could open startup-sequence which you can find in drawer &quot;S&quot;. There should be a line: 
 Assign THEMES: SYS:SYSTEM/THEMES &gt;Nil: 
This does the trick. 
Open a shell and run: 
 Assign THEMES: SYS:SYSTEM/THEMES 
Than start the Theme prefs again... this should work 

* The theme is the only thing that could slow the system a bit, but it's not that performance impacting on most uses, and you can switch it off completely. Remove C:Decoration from the bottom of the file sys:s/startup-sequence. 

In each theme directory is 
*Env-Archive -&gt; Zune -&gt; global.prefs
*images -&gt; Gadgets -&gt; 20x20 pngs for Down etc 
*menu -AmigaKey - Background - Checkmark - SubMenu and config
*system - Arrowdown, Arrowleft, Arrowright, Arrowup, etc 


There is an [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/theme ALua/Zulu script] built for faster Wanderer skin management. You can modify config files, install new (wdz format/zipped skin files) and delete skins via the Theme Manager. This has not been updated in a long time and may not work. 


Certain features are added if from Tools/Commodities like Blanker screensaver, ClickToFront and DepthMenu with .info icons are selected and dragged to /WBStartup folder 

Most apps can be autostarted by copying into SYS:WBStartup directory folder 
e.g. WeatherBar.zip can be downloaded, unzip and the contents of the zip copied to wbstartup folder 
 ClicktoFront and .info to SYS:WBStartup so always be activated when turning on the computer 

or add a text line to user-startup is SYS:S (scripts version of wbstartup) 

e.g. standard Amiga / AROS does not allow clicking of background windows to come to the front to make it easy to get to the window you need but it has the ability if these apps are copied again to WBStartUp or are added to SYS:S/user-startup script 

 run QUIET sys:Tools/Commodities/ClickToFront &gt;Nil: 
 run QUIET sys:Tools/Commodities/DepthMenu &gt;Nil: 
 run QUIET sys:Tools/Commodities/Blanker seconds=300 &gt;Nil: 


Exchange controls Commodities and can be opened with alt, ctrl, h 

*AltKeyQ uses left Alt key to add strange letters 
*AutoPoint 
*Blanker screensaver 
*ClickToFront allows windows to be easily brought to the front 
*DepthMenu adds menu to select window easily 
*NoCapsKey
*Opaque 
*FKey - Although there are heaps of docks, menus and other launcher programs on the Amiga like OSs, FKey has got to be one of the quickest once learnt ways to launch programs, and it comes with the OS. In SYS:Tools/Commodities, the FKey commodity (Ctrl Alt F) allows you to make actions assigned to some combinations of keys 

&lt;pre&gt;
ALT TAB       Cycle Windows
              Cycle Screens
              Enlarge Window
              Shrink Window
              Toggle Window Size
              Insert Text
              Run Program
              Run Arexx Script
&lt;/pre&gt;

e.g.
&lt;pre&gt;
LAmiga F1               = Avail Flush
LAmiga F2               = Open Prefs
LAmiga F3               = Finder
Alt Tab                 = Cycle Windows
LAmiga Tab or M         = Cycle Screens
Alt Up arrow            = Enlarge Window 
Alt Down arrow          = Shrink Window
Alt Home                = Toggle Window Size 
                        = Insert Text             
LAmiga e                = Run Program             
                        = Run Arexx Script        
&lt;/pre&gt;

If your FKey GUI pops up when you start your Workbench up and you don't want it to, click once on the icon, go to the Icons-Information in the menu and make sure it has the tooltype set &quot;CX_POPUP=NO&quot;. 

Now let's launch it and assign the locale switching. After you double-click on FKey icon, launch the Exchange, choose the FKey from list and click the Show button. This will invoke the FKey window. You can see the ALT TAB in list assigned to window switching. Now enter the first key combination, say, ALT Z and go to the right panel. Choose Launch the program from pulldown menu and enter SYS:Prefs/Input as an argument. Append the USE switch and english preset name to the string as shown:

SYS:Prefs/Input USE SYS:Prefs/Presets/english

Click on the New Button to add the another combination. Now set the combination for your locale as shown above, replacing English name with your preset name. Click New button again and then Save Settings. Now you can use defined combinations to switch the layouts.


There is a system wide ARexx script capability (based on regina) that can manage many file manipulation task(s) but this would work only with those program that support [https://en.wikibooks.org/wiki/Aros/Developer/Docs/Rexx ARexx] like 

*Desktop - DOpus5, Scalos 
*Dock - FKey, 
*Files - Multiview, DOpus4, 
*Internet Apps - Odyssey, WookieChat, 
*General Apps - 


the shell can be modified with escape strings but not needed in most cases 


 Common Keyboard Shortcuts

&lt;pre&gt;
RAlt Right Alt Key 
LAlt Left Alt Key 
RWinKey Right Windows Key 
LWinKey Left Windows Key 
RAmiga Right Amiga Key (if one)
LAmiga Left Amiga Key (if one)
&lt;/pre&gt;

;Bootup Options 
:Spacebar during boot, enters the bootmenu which allows a boot without startup sequence, etc  

;Left Click 
:LAmiga = LWinKey = F11 

;Right Click 
:RAmiga = Help = F12 

;Mark 
:RAmiga and B 

;Cut 
:RAmiga and X 

;Copy 
:RAmiga and C 

;Paste 
:RAmiga and V 

;Search 
:RAmiga and S 

;Mouse Movement 
LAmiga and together with arrow keys - shift as well at the same time as well to move faster 

;Mouse Selection 
LAmiga and LAlt to select 

;Screen Switching 
LAmiga and M or N 

;HELP key 
Can sometimes be mapped to F11 but can be changed via FKey 


ComKeyRemapper or AmigaKeyremapper could swap RAmiga to another key press 


===DOpus 5 Directory Opus Magellan II===

Dopus 5.x is a whole desktop replacement on the Amiga Workbench (Desktop) 

DirectoryOpus app will assign DOpus5: to it's PROGDIR: automatically but if not add the below (edit SYS:System to suit where Dopus5 was installed) to your startup-sequence 

&lt;pre&gt;
Assign DOpus5: SYS:System/DOpus5 
DOpus5:DirectoryOpus 
;DOpus5:C/LoadDB
&lt;/pre&gt;

Left mouse button clicked twice on the desktop background brings up the Device List window. 
Green strip notifies SRCE (source) and if another is open it will be red for DEST (destination). clicking on the red strip changes to green 

Word list of actions with a left mouse click on the DOWN Arrow and directory stuff with &lt; button which mirrors the icons at the top of each lister 

single-key hotkeys? exactly the same as in dopus4, edit your functions (button bank, toolbar, menus etc.) and under the flags gadget is a key gadget, just click in it and press the key you want to use.

As for the extra text field... try turning off Extended lister key selection in environment / miscellaneous.

Shift and click on the icon - runs the icon 


DOpus5 Magellan 2 Directory folder drawer structure 
&lt;pre&gt;
ARexx       - Arexx scripts .rexx and .dopus5 to perform tasks 
Buttons     - 
Commands    - 
Desktop     - 
Environment - two environment files bundled:
 default gets loaded if you run DOpus as a normal app
 workbench gets loaded if you run DOpus as a WB Replacement (with LoadDB on startup)
Filetypes   - 
Groups      - 
Icons       - 
Images      - 
Modules     - compiled tasks 
Settings    - 
Sounds      - 
Themes      - 
WBStartup   - Use this if standard SYS:WBStartup gives cannot wait error messages 
&lt;/pre&gt;


Settings -&gt; Environment -&gt; Display -&gt; Workbench (Use) 


*Settings -&gt; Clock (add to title bar as well as the date) 

*Toolbar  -&gt; Editor (Right Win Key together with 1) for Copy, Move, Delete, etc above the Device List 
*Menu     -&gt;  (Right Win Key together with 2) 
*Buttons  -&gt; Editor (Right Win Key together with 3) 

*Settings         -&gt; Environment (Right Win key together with 4) for Backgrounds, etc 
*File Types       -&gt;  (Right Win key together with 5)
*User Menus       -&gt;  (Right Win key together with 6)
*Hotkeys          -&gt; Setup for quick shortcut keypresses (Right Win Key together with 7) 
*Scripts          -&gt;  (Right Win key together with 8)
*Icon Positioning -&gt;   (Right Win key together with 9)


Each Dopus5 theme are stored in a separate directory, named appropriately, which contains further sub directories 

* Font (amiga bitmap fonts)
* Screens (jpg or any picture supported by datatypes but not animations) 
* Sounds (wav but not iff 8svx ) 
* Icons (png newicons glowicons ) 
* Patterns (iff jpg png ) 


Just use wildcards in background filenames and you get a different picture every reboot 

For example, configure in Environment -&gt; Backgrounds -&gt; Desktop something like this:
&lt;pre&gt;
Work:Pictures/Backgrounds/#?
...or 
Work:Pictures/back#?.iff
...etc...
&lt;/pre&gt;


[https://aminet.net/util/dopus arcdir and themes]  


If you want to change the backdrop pic after a period of time, paste below into a text file called dopusrandbg.rexx and place in DOPus5:ARexx 

&lt;pre&gt;
/* Changes DOpus background image forever

   Start with:
   Run &gt;NIL: RX dopusrandbg.rexx 
*/

if ~show(&quot;L&quot;, &quot;rexxsupport.library&quot;) then do
	if ~addlib(&quot;rexxsupport.library&quot;, 0, -30,0) then exit 10
end

/* Configure these two lines for your needs: */
minutes=1
picpath=&quot;Work:Pics/#?.iff&quot;

address DOPUS.1

do forever
	call delay 3000*minutes
	dopus set background '&quot;'picpath'&quot;' desktop center custom
	dopus refresh background custom
end
&lt;/pre&gt;


If you don't want to use/open rexxsupport.library just for DELAY() then use the DOS Wait command

&lt;pre&gt;
/* random diropus backdrop changer */
/* by paul trauth, 1999 */
/* to do: non-repeatable randomness? */

options results

parse arg path

address DOPUS.1

/* get current backdrop pattern so it actually changes */

dopus query background desktop custom
currentpatt=result
lastslash=lastpos('/',currentpatt)
currentpatt=substr(currentpatt,lastslash+1,(pos('&quot;',currentpatt,2)-lastslash-1))

dir=showdir(path,'FILE','/')
num=0
do while dir~=''
    where=pos('/',dir)
    if where&gt;0 then do
        file=left(dir,where-1)
        dir=right(dir,length(dir)-where)
    end
    else do
        file=dir
        dir=''
    end

    if left(file,1) ~='.' &amp; file~=currentpatt then
        do
            pics.num=file
            num=num+1
        end
end

which=random(0,num-1,time(s))
newbg='&quot;'||path||'/'||pics.which||'&quot;'

dopus set background newbg desktop tile precision exact
dopus set background on
dopus refresh background
&lt;/pre&gt;


Clock format commands available are defined by locale. They are:
&lt;pre&gt;
 %a - abbreviated weekday name
 %A - weekday name
 %b - abbreviated month name
 %B - month name
 %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
 %d - day number with leading 0s
 %D - same as &quot;%m/%d/%y&quot;
 %e - day number with leading spaces
 %h - abbreviated month name
 %H - hour using 24-hour style with leading 0s
 %I - hour using 12-hour style with leading 0s
 %j - julian date
 %m - month number with leading 0s
 %M - the number of minutes with leading 0s
 %p - AM or PM strings
 %q - hour using 24-hour style
 %Q - hour using 12-hour style
 %r - same as &quot;%I:%M:%S %p&quot;
 %R - same as &quot;%H:%M&quot;
 %S - number of seconds with leadings 0s
 %T - same as &quot;%H:%M:%S&quot;
 %U - week number, taking Sunday as first day of week
 %w - weekday number
 %W - week number, taking Monday as first day of week
 %x - same as &quot;%m/%d/%y&quot;
 %X - same as &quot;%H:%M:%S&quot;
 %y - year using two digits with leading 0s
 %Y - year using four digits with leading 0s
&lt;/pre&gt;
like %a %d-%b-%y %H:%M or 


A WB ARexx interface, you could enter a cli command as a menu item to open a WB drawer like this...
 RX &quot;address WORKBENCH;WINDOW 'device:drawer' OPEN&quot;
Where device:drawer is replaced by the path of the drawer to open. 

The ARexx script would be capable to manage such a task but this would work only with those program that support ARexx 

&lt;pre&gt;
dopus addappicon
dopus addtrap
dopus back
dopus checkdesktop
dopus clear
dopus command
dopus desktoppopup
dopus error
dopus front
dopus getdesktop
dopus getfiletype
dopus getstring
dopus matchdesktop
dopus progress
dopus query background, font, palette, pens
dopus read
dopus refresh all, background, icons, lister
dopus remappicon
dopus remtrap
dopus request
dopus script
dopus screen
dopus send
dopus set background, font, palette, pens
dopus setappicon
dopus version
&lt;/pre&gt;

&lt;pre&gt;
lister add
lister addstem
lister copy
lister clear value
lister clearcaches
lister close
lister empty
lister findcache
lister getstring
lister iconify
lister new
lister query active all, dest source
lister query abort, busy, case, dirs, display, entries, entry, files, flags, handler, header, hide 
lister query label, lock, mode, namelength, numdirs, numentries, numfiles, numseldirs, numselfiles
lister query path, proc, position, seldirs, selentries, selfiles, separate, show, sort, 
lister query title, toolbar, value, visible, window
lister read
lister refresh
lister reload
lister remove
lister request
lister set busy, case, dest, display, field, flags, handler, header, hide, label, lock, mode
lister set namelength, newprogress, off, path, position, progress, separate, show, sort, source
lister set title, toolbar, value, variable
lister select
lister wait
&lt;/pre&gt;

The '''command''' allows you to call internal DOpus commands from an ARexx script

&lt;pre&gt;
command all
command wait copy
command read s:startup-sequence
command source 12345 makedir name noicon
&lt;/pre&gt;


*SFTP secure encrypted comms over internet using libssh2 and zlib (different protocol to the two below) on port 22 
*FTPS secured with https like security on port 21 
*FTP not secure and unencrypted protocol over internet on port 21 (should not be used today on the internet but for your own server) 


===Wanderer ===


Wanderer prefs in the prefs drawer - Appearance tab and Workbench icon allows backgrounds (wallpapers) icon text sizes, colors, etc but cannot use #? or *.* in the backgrounds file entry to randomly choose pictures - [https://developers.google.com/speed/webp/docs/riff_container webp riff container] issues with this format but Multiview has none. 

Enable the bar, you need to edit the text file ‘statusbar.prefs’. The change is simple: just change “False” to ‘True’.

Prefs/Env-Archive/SYS/Wanderer/statusbar.prefs 


===Scalos===

[https://web.archive.org/web/20180922220139/http://scalos.noname.fr/ Scalos] is not an OS replacement, it's a Workbench replacement. It replaces the desktop and graphical file management components. 

Scalos is 100% Workbench replacement with most functions working like the original Workbench ones. Undo and Redo available for most window and icon operations. Fully multitasking so every window has its own task. While loading icons, any window function (e.g. Drag&amp;Drop) is available. 

24bit color support with window patterns - Unlimited and easily configurable via tooltypes. Optimised backgroundpatterns routine so patterns can be tiled, centred or even scaled to fit into the windows. Live updating window scrolling - Supports middle mouse button panning and drawer (folder) windows can be iconified on the desktop. 

Icon imagetypes with all types are supported such as backfill or complement. Configurable surrounding iconborder. Icon support also visually highlights files which are soft-links in the file system. Icon dragging is more stable and far less flickery on graphics cards. Whilst dragging, icons are displayed with text and they can become transparent over anything where they can be dropped. 

Single-window lasso mode, with scrolling window contents invoked by dragging mouse with configurable qualifier key. Text icon lasso selection used to ignore &quot;Name column selects text icons&quot; flag. Support for backfilled thumbnail icons, with selectable color and transparency. Added option to always generate square thumbnail icons with preview icons for images - Thumbnails can be permanently saved in icons. 

Supports PNG icons with alpha channel and real transparency and displays OS3.5 GlowIcons and are all scalable. Iconborders with variations (normal, shadowed, outlined). 

Completely configurable, filetype-specific user-definable popup menus and tooltips. Plugin system to exchange or add features and can enhance the Workbench and make it more configurable. 

Filetype plugins to display filetype-specific information. - Currently, EXIF information viewer for JPEG images is included. Plugin included for 100% support of OS3.9 Workbench features. Plugin included for AREXX API compatible to OS3.9 Workbench. 

Online update with updater.module


Scalos works also as a Workbench replacement. In this case the 'emulation mode' has to be set by using Scalos' own version of LoadWB and offers 
* Scalos uses the Workbench Screen for its windows instead opening a new one 
* AppIcon, AppMenuItem, AppWindow functions are redirected to Scalos
* all Programs placed in &quot;WBStartup&quot; should start 
* The Screen will be reopened in case of changes in ScreenMode and Palette settings


&lt;pre&gt;
v1.0 (V39.201) - November 1999
v1.1 (V39.212) - December 1999
v1.2b (39.220) - June 6, 2000
v1.2d (39.222) - 2000 (latest public beta executable)
v1.3 (40.7) (beta) - August 2, 2001
v1.3 (40.22) - September 25, 2002
v1.4 (40.32) (beta) March 31, 2005
v1.6 (41.4) - March 27, 2007
v1.7 (41.5) - August 12, 2007
v1.8 (41.6) - March 12, 2009
v1.9 (41.7) (beta) - March 15, 2010
v1.9 (41.8) (RC1) - August 25, 2012 open source 
v1.9.2 (41.10) Deadwoods' AROS late 2022 32bit and 64bit build unifying the code base of ` for AROS x86 ABIv0, AROS x86_64 ABIv11 and AROS m68k  
&lt;/pre&gt;


Distros may have Scalos files under SYS:System/Scalos or Extras:Scalos. Known [https://github.com/deadwood2/AROS/issues/75 bug list], 


 Certain files like Menu13.prefs, Palette13.prefs, Pattern.prefs and scalos.prefs need to be in SYS:Prefs/Env-Archive/Scalos they can be found in Scalos:Storage/envarc and country drawer 

or run the &quot;Scalos Menu&quot; preferences program. Note if already setup with sub-menu entries and then re-save your menu prefs as it will now generate a new/overwrite prefs file called &quot;Menu13.prefs&quot; in &quot;envarc:scalos/&quot;. The same is also required for the new Palette prefs update, click 'Save' and a &quot;Palette13.prefs&quot; file will be saved in to &quot;envarc:scalos/&quot; directory. 


&lt;pre&gt;
ASSIGN Scalos:             SYS:xxx/xxx DEFER   
ASSIGN Libs:               Scalos:Libs add    
;ASSIGN SYS:Devs/Datatypes  Scalos:Devs/Datatypes   add  
Assign Theme:              Scalos:Themes/Default_Theme add 
Assign Locale:             Scalos:Locale add 

Protect Scalos:Tools/browse.script s add quiet 
Protect Scalos:Tools/OpenShell s add quiet 
Protect Scalos:Tools/run.script s add quiet 

run Scalos:Tools/LoadWB 
;Scalos:Scalos
&lt;/pre&gt;

Add the above to SYS:S/startup-sequence or SYS:S/user-startup '''before any Wanderer entries''' 


In the prefs drawer (folder) is the big prefs app Scalos_Prefs which covers these user setup areas 
&lt;pre&gt;
About Scalos
Paths               - should be preset 
Startup             - WBStartup drawer contents should auto run on each startup 
Desktop             - edit titlebar, icon layout and in misc, auto leave-out (drag icon to desktop) 
Icons               - 
Drag and Drop       - 
Windows             -
Text Windows        -   in misc, drawer sorting at start of listing if needed 
TrueType Fonts      - use Truetype fonts rather than system ones 
Miscellaneous       - 

Plugins             - after adding oop/title_clock.plugin %ti %da does not work, maybe needs ASCII .prefs added 
Modules             - ??
Menu                - setup for MainMenu and PopupsMenu with New Menu, RE Name, Key: shortcut, Command Properties 
FileTypes           - already added def_Project icons and def_Disk (hdd sdd cd dvd etc) support 
PopupMenu           - tweak how popups appear 
Pattern             - Wallpaper backgrounds with Type DE, each pattern in the list can be edited, Save as Pattern.pre 
Palette             - change the color of things , Save as Palette.pre 
&lt;/pre&gt;


Scalos_Prefs - Pattern - Minimum options to be changed are 
*DE Desktop/Background 
*SC Screen 
*TW Window/TextBackground ie Text listing showing if icon type not recognised 
*IW Window/Background ie Icons showing 

 Workflow - In &quot;Pattern List&quot; tab, select New - choose a picture, highlight in list, click in number box under New button and slide to another number, click on &quot;Defaults&quot; tab and adjust Pattern numbers slider to choose right picture for each of the above options - Click &quot;Pattern List&quot; tab to check eveything is OK and click Save 

Pattern List tab on Patterns Page - Allows you to compile a list of pictures (one at a time rather than a whole folder e.g. with #? or *.*), assigning a number Nr to one or more of them for easy reference. Using this number you will be able to assign the pictures to specific windows on the Defaults tab Page. If multiple pictures have the same number, one of the pictures will be chosen randomly. This will allow you to have random desktop pictures, random window backdrops etc. 

Defaults tab on Patterns Page - Here you can set the defaults for the background pictures for the Desktop, Screen, Window and/or Text Mode throughout Scalos. 
Randomize every time [check box] - Usually Pictures with the same number will be randomly selected as soon as the configuration loads. If this option is set, the picture will be selected as soon as a window with the same number assignment is opened. 

*Fit size: The picture will be resized to the dimension of the new window.You *MUST* have set GUIGfx on. asyncron layout: Pictures will be loaded and rendered while the windows opens (Like original Workbench). If this function is 'off', pictures will always be loaded before opening the windows. 
*Use friendbitmap : The picture is present twice in memory for best speed. This option has no effect if V43 picture.datatype or GUIGfx are used. Always relayout: If &quot;Fit size&quot; is set, the picture will be scaled everytime the window's dimensions change.
*Randomize everytime: Usually Pictures with the same number will be randomly selected as soon as the If more pictures have the same number, one of them will be chosen randomly. 

Patternlist New/Delete : Add a new picture. After that you should assign a number to it. The picture will be rendered as tiles. configuration loads. If this option is set, the picture

Asyncron-Task priority: You can set the CPU priority for the Task if &quot;asyncron layout&quot; is set. 
&lt;pre&gt;
Desktop: Number of the Picture for the main window.
Screen: Number of the picture for the Scalos-Screen.
Window: Number of the picture for the Scalos-windows.
TextMode: Number of the picture for the Scalos-windows in Text Mode.
&lt;/pre&gt;


Popup Menu preferences fully configurable menus (includes ToolsDaemon and ParM launch apps import), including support for context-sensitive Popup menus configs for top pull down menus for apps, etc. 

 Workflow - Scalos_Prefs then Menu, New Item, New Command add name at top then in Command Properties e.g. add Workbench and location e.g. DOpus:DOpus4 for apps  Command for c apps or Rexx for scripts or Plugin for  or AmigaDos for modules 

&lt;pre&gt;
DESCRIPTION	NAME/A      This is the title that is displayed in the top line of any popup menu  
INCLUDE NAME/A          Name of file to be included. Path can be relative to &quot;Scalos:FileTypes&quot; 

POPUPMENU      Starts the popup menu description section for this filetype.
&lt;/pre&gt;

The following Subcommands are allowed inside popup menus:
&lt;pre&gt;
SUBMENU &quot;NAME/A&quot;
ENDSUBMENU 


MENUENTRY &quot;NAME/A,KEY/K,DEFAULTACTION/S&quot;
ENDMENUENTRY 

INTERNALCMD	&quot;NAME/A&quot;
WBCMD &quot;NAME/A,STACK/K/N,WBARGS/S,PRI=PRIORITY/K/N&quot;
AREXXCMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;
CLICMD &quot;NAME/A,STACK/K/N,WBARGS/S,P=PRIORITY/K/N&quot;

ICONWINDOWCMD &quot;NAME/A&quot;

PLUGINCMD
MENUSEPARATOR

ENDPOPUPMENU

TOOLTIP 
ENDTOOLTIP
&lt;/pre&gt;

&lt;pre&gt;
Starts the tooltip description section for this filetype. The following Subcommands are allowed inside popup menus:

GROUP &quot;ORIENTATION/K&quot;
ENDGROUP  
MEMBER &quot;HIDE/K&quot;
ENDMEMBER  

HBAR 
STRING &quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;
SPACE &quot;SIZE/N/A&quot;

DTIMAGE &quot;FILENAME/A&quot;
&lt;/pre&gt;


Each theme drawer (folder) has these further folders 
&lt;pre&gt;
About            - 
Desktop          - 
FileTrans        - 
FileType         - 
Icons            - 
Menu             - 
Modules          - 
PointerIcons     - 
Prefs            - 
Sound            - 
Window           - 
&lt;/pre&gt;


*Plugins
&lt;pre&gt;
devicefilter.plugin       
persist.plugin            should a crash or reboot occur - next time Scalos started, all windows re-opened 
title_clock.plugin        add digital clock to title see more below 
title_envvar.plugin       %ev, which can be used to display the value (a string) of the variable in the titlebar 
title_freepens.plugin     
volumegauge.plugin        
wb39.plugin               
wbrexx.plugin             plugin adds a Workbench 3.5+ compatible AREXX interface to Scalos internals 
xtwindows.plugin          left or right ALT or left or right SHIFT keys when open/close windows 
filetype.plugin           then run FileTypes-prefs and customize the filetypes (eg import from a DefIcons-brainfile) 
menu.plugin               
&lt;/pre&gt;


*Modules - delete, empty_trashcan, execute, find, format_disk, information, iconproperties, newdrawer, reboot, rename, systeminfo, windowproperties 


*Tools - scripts like LoadWB, quit.rexx, open_volume.rexx, 


In Scalos_Prefs-&gt;Filetype-&gt;Recognition  you can define the filetypes and on &quot;Action&quot; you define specific context menu for all filetypes defined in recognition (similar to magellan)
there is the same you must show all first (list is only limited) so you created a file type AAABBB, you need to have def_AAABBB icon 

Associating files with &quot;Scalos_FileTypes&quot; is very simple, practically it is very similar to Dopus4, first you create the Def_icons to assign to the file type (will be seen automatically ), then run &quot;Scalos_FileTypes&quot; you add the extension, fill in the descriptor (MATCH or PATTERN etc..) and save 

then you create a appropriate entry in the list and rename it, if def icon exists it is shown. Below you can define how files are identified. I use &quot;pattern&quot;, similar to magellan to identify file by ending. Then you click on the shown icon and define in it what program is used when you double-klick on it and save it. On the tab action you can define popup menu for it. 

defined all archive types from XAD in &quot;filetypes&quot;. If you change to &quot;action&quot; and click on &quot;archive&quot; you can define the context menu that is shown if you do not define a specific context menu for a filetype


Reset to Default in Scalos_Prefs resets all settings so BEWARE 


&lt;pre&gt;
The Scalos desktop screen titlebar may be configured using the main Scalos Preference program. This oop/time_clock plugin adds some additional placeholders:

    %ti, displays the current time in the default Locale format. e.g. &quot;10:43:37&quot;
    %da, displays the date in the default Locale format. e.g. &quot;Saturday 14 July 2001&quot;

Using the supplied prefs program for the plugin, or editing the ASCII file ENVARC:Scalos/title_clock.prefs you can use the following standard Amiga Locale values to change the formatting 

    %a - abbreviated weekday name
    %A - weekday name
    %b - abbreviated month name
    %B - month name
    %c - same as &quot;%a %b %d %H:%M:%S %Y&quot;
    %C - same as &quot;%a %b %e %T %Z %Y&quot;
    %d - day number with leading 0s
    %D - same as &quot;%m/%d/%y&quot;
    %e - day number with leading spaces
    %h - abbreviated month name
    %H - hour using 24-hour style with leading 0s
    %I - hour using 12-hour style with leading 0s
    %j - julian date
    %m - month number with leading 0s
    %M - the number of minutes with leading 0s
    %n - insert a linefeed
    %p - AM or PM strings
    %q - hour using 24-hour style
    %Q - hour using 12-hour style
    %r - same as &quot;%I:%M:%S %p&quot;
    %R - same as &quot;%H:%M&quot;
    %S - number of seconds with leadings 0s
    %t - insert a tab character
    %T - same as &quot;%H:%M:%S&quot;
    %U - week number, taking Sunday as first day of week
    %w - weekday number
    %W - week number, taking Monday as first day of week
    %x - same as &quot;%m/%d/%y&quot;
    %X - same as &quot;%H:%M:%S&quot;
    %y - year using two digits with leading 0s
    %Y - year using four digits with leading 0s

 like %d %m %y or %a %d %B %Y %p
&lt;/pre&gt;


Shutdown -&gt; right mouse button Scalos, About, Reboot, Shutdown 


ToolTypes can be added to the Scalos.info icon like 
*SCALOS_PATTERNNO=&lt;number&gt; : background image matching the number 
*SCALOS_NOTEXT : The Icon will be drawn without Text.
*SCALOS_NODRAG : The Icon will not be draggable. Its position will be fixed.
*Module iconproperties - Added SCALOS_BROWSERMODE tooltype support

runcommand parameters... in which case:
&lt;pre&gt;
%p = parameters
%w = directory path
%d = device-name
%% = literal percentage token
&lt;/pre&gt;


With the help of the wbrexx.plugin Scalos gains support for more of the compatible arexx API 

If an arexx command produces an error you will find the error code placed in the WORKBENCH.LASTERROR variable.

ACTIVATEWINDOW
&lt;pre&gt;
/* Activate the root window */
ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the &quot;Work:&quot; partition's window if already open*/
ACTIVATEWINDOW &quot;Work:&quot;
&lt;/pre&gt;

CHANGEWINDOW
&lt;pre&gt;
/* Change the root window; move it to position 10,30. * and change its size to 200100 pixels */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window */
CHANGEWINDOW active 20 40 200 100
&lt;/pre&gt;


Most of Scalos' issue are due to the flexibility of its' user configuring nature but if 


The sort menu plugin needs to be ported from ASM to C.

IIRC Scalos has a command line option to fully replace Workbench/Wanderer.

The Theme: assign is used by both Wanderer and Scalos but I didn't have any problems using both at the same time.


The Program will be started from the Shell.
If &quot;WB Args&quot; is set, with the Argument &quot;%p&quot; will be replaced by the path of the activated Icons. The Program will started with the specified Stack value.
IconWindow: Scalos opens the window of the specified path.


PlugIn: Starts a Scalos Menu-PlugIn.
If a Menu Item with empty name is specified, Scalos displays a separator line.
It's possible to Drag&amp;Drop an Icon in the Configuration Window. All values will be set accordingly. Entries may be dragged across the list.


Mac-like selection : This function activates a multiselection method used on MacOS or Win95. Don't have to hold down shift to drag them. Clicking on an already activated icon will
not deselect all other icons. 

MMB move: The window contents may be moved using the middle mouse button. 

WindowPopup title only: PopupMenu for windows can be opened only on window's title bars. 

FullBench: Screen-Titles removed and Main Window set Full Size. 
Scalos Prefs. Go to Settings-&gt;Scalos-&gt;Prefs and then the Misc section. Remove the tick against Full Bench. If you've enabled it, the titlebar will disappear when you select backdrop.


Default Icons saveable : The icons which Scalos generates if &quot;show all files&quot; is enabled, can now be saved
using &quot;snapshot&quot; menu option. load DefDisk first : Try to read the icons first from the DefIcons Path before using disk info. 


Hide hidden files : If this function is activated all files or directories where the &quot;hide&quot; flag is set will not be shown.

Many of my Icons display more than once on the screen, while on the workbench all seems ok.
The Workbench filters double displayed icons, Scalos does not. Solution: please edit the &quot;.backdrop&quot; file and clear double lines.

Background images not scaled. GUIGfx option not set or guigfx.library and/or render.library not installed.

If working with CD's causes crashs or Scalos doesn't work correctly.
Most Filesystems doesn't support the ExAll function correctly. Disable &quot;Use ExAll&quot; in Scalos prefs.

Scalos doesn't start any program in the WBStartup. WBStartup Path may be set wrongly or Scalos was not started in Emulation Mode (LoadWB etc) 
Some programs will not startup with error message &quot;has not returned, wait some more&quot;? and &quot;unable to open your tool&quot; 


need a def_icon with the same name predefined, then create an appropriate entry in the list and rename it, if def icon exists it is shown. Below this can define how files are identified. 
* either &quot;pattern&quot;, similar to magellan to identify file by ending
* or 
Then click on the shown icon and define in it what program is used when you double-click on it and save it. On the tab action you can define popup menu for it. All in all handling is of course different to magellan but can do similar 

For the RAM Icon, to obtain this you have only to copy the icon in the Icon Path as &quot;RAM.info&quot; or &quot;Ram Disk.info&quot;. All functions will automatically be performed 

sometimes cut into half or quarters when scrolled off screen or drawers moved - settings issue probably  

Sometimes leaves initial drawer window imprint on desktop when moved - settings issue 


Scalos AROS released a [https://github.com/deadwood2/contrib/tree/master/scalos new build V2022-07-21] with the following changes noted:
&lt;pre&gt;
Fixed:
    Numerous crashes when working on 64-bit with 64-bit heap
    Wrong background color of Scalos logo on Scalos splash window
    Backgroung image of Scalos splash window and Scalos About window is not visible
    Icon labels on desktop and in drawer windows are displayed using Topaz instead of Arial font
    Font.prefs are not being loaded on 64-bit
    Font.prefs are being wrongly saved on 64-bit
    scalos.prefs are not being loaded on x86 and x86_64, scalos is using always default preference
    scalos.prefs are being saved on x86 and x86_64 in format not compatible with m68k 
    NewPopupmenu.prefs is wrongly written
    Plugins are not loading at Scalos startup
    wbrexx.plugin is crashing at startup on 64-bit
    Multiple controls missing on Scalos Prefs/Icons page
    System crash when clicking on def icon image on FileTypes Prefs/Recognition page
    Status bar, control bar, buttons sometimes don't have images displayed
    Buttons in Scalos About window have white corners rendered where they should be transparent
    Crash when leaving out an icon
    Crash when adding a User-defined Button to Control bar without setting it's properties in Scalos Prefs
    Crash when removing any button from Control bar in Scalos Prefs
    Scalos Prefs allows editing TTEngine font properties when TTEngine is not present causing crash in Icons/Labels and Text Windows/Fonts pages
    deficons.prefs are not being loaded on x86 and x86_64
    Reset to default in FileType Prefs and Save does not save preferences

Won't fix:
    Scrollbars visible on titles of TrueType Fonts, PopupMenu, Menu, FileTypes, Pallette and Pattern pages of Scalos Preferences

Not fixed:
    Wrong rendering on DualPNG icons 
    Refreshing drawer windows is slow 
    Starting Prefs/Locale or Prefs/Input from Scalos causes other preferences to fail 
    Desktop wallpaper is damaged where Splay window was displayed 
    When started from Wanderer, after saving Scalos Prefs, reload does not re-open main Scalos window
    Difference in behavior between Cleanup from popup menu and Cleanup from top menu - possibly due to missing plugin, check Cleanup association in Menu Prefs
&lt;/pre&gt;


===DOpus 4 Directory Opus===

Copy DOpus4 app to WBStartup directory folder so it starts on boot up each time 

Another method is add the below to the bottom of the user-startup script in S: drawer/directory 
&lt;pre&gt;
run DOPUS:DirectoryOpus -i &gt;NIL
&lt;/pre&gt;
makes DOpus starts up in Iconified state at the top of Wanderer's screen. Left click on this to highlight and right mouse click to open. 


Just click on the sides of either outer edges of DOpus windows and it will display the parent device/volume list. 


DOpus saves it features in a CFG file which can be edited to suit anyones' needs by reading the [http://archives.aros-exec.org/index.php?function=browse&amp;cat=utility/filetool Dopus Manual] which is in Guide format. 


===BoingIconBar===

User chooses the apps to add to the dock at the centre bottom of the screen but has to be done manually, please use Save afterwards 

Or easier edit the text file of SYS:Prefs/Env-Archive/iconbar.prefs and save 

&lt;pre&gt;
SYS:System/Shell 
SYS:Tools/DOpus4/DOpus4
SYS:Utilities/Editor
SYS:System/SysMon
SYS:System/Scout
Work:Extras/Internet/OWB/OWB
Work:Extras/Graphics/Lunapaint
Work:Extras/Graphics/ZunePaint
AROS:Tools/MPlayer/MPlayer
Extras:Internet/AmiFox/AmiFox
&lt;/pre&gt;

right mouse click on bottom edge of screen where boingiconbar shows - select settings which opens BoingIconBar Preferences to add apps 

If no dock showing Add, to add apps click Add Program and search for the executable 

another method is to drag icons to ends of the bar and move them on the Bar using the Prefs/BoingIconBar 


===AmiStart===

On 32bit PCs only - auto generates the apps menu but scans the drive each time - AmiStart can choose apps you are not interested 

* how to disable annoying zune/mui 'bubbles'? 
try a right-click on AmiStart and release on Global settings. Then click on the bubbles gadget. Move the Show Bubbles slider all the way to the left.


===Fonts===

Install the #?.ttf files to SYS:Fonts/TrueType. Use SYS:System/FTManager to &quot;Install Font&quot; each #?.ttf file which will generate associated #?.otag and #?.font in SYS:Fonts. Use SYS:Prefs/Fonts to change system fonts and SYS:Prefs/Zune to change others. 

To achieve our goal we will use the Setup Locale, Input, Zune and Fonts, as well as The FTManager.

Begin

The first step you should do is to get the system to know that we speak and write in another language. What you need to do is to open the setup program and choose Locale country, and list &quot;preferred languages&quot; to put it first and then English. If you want the tab &quot;Time Zone&quot; and select city of residence to set the clock correctly. Of course we save our changes and continue opening the setup program Input. This sets the keyboard language as our beginning. When the language layout was created there was no option to switch to Aros keyboard (layout switching), so to write in the language you had to hold down Alt, something you encounter in other functions. This time working with the team of Aros to create a new keyboard layout to replace the old so we can get rid of the button Alt. For now though let only selected this layout and do not turn the switch on the keyboard.


Custom Keyboard Layout

[http://repo.or.cz/w/AROS.git/tree/HEAD:/workbench/devs/keymaps keymaps are in place but unfortunately when they are not, then indeed things become a bit 'low-level' as it involves redefining some tables with values that match your keyboards] 

only need to add your compiled table as new keymap. 

So taking a little peek here shows that it should be possible to compile using
 gcc -opc105_tr pc_105.c -nostdlib
where the pc105_gr/pc_105.c needs to be replaced with your own adjusted keymapname/c-file

[https://en.wikiversity.org/wiki/Enabling_Greek_Characters_on_Your_Keyboard General overview of Greek letters on keyboards] 


Installing fonts

*[http://aminet.net/package/util/wb/EPAGrWb System jaggy] 
*Outline resizable .font .otag 
In this step you need to download some fonts that can support the encoding in our system. The easiest way is to run the script &quot;Download Fonts&quot; you'll find in the folder OWB. This script downloads from the Internet, and unpacks some fonts for OWB web browser, which is placed under the folder Fonts:TrueType. But as these can only be used by OWB and not the system, which unfortunately does not see. To make them available to the rest of the system, open the program FTManager, you will find the folder AROS: System /. From there select the field &quot;Codepage&quot; option &quot;ISO-8859-7&quot; and list the font &quot;Arial&quot; and &quot;Regular&quot; form in which you must double-click with the mouse. In the window that appears, select the bottom right the checkbox &quot;Anti-aliasing&quot; button and then &quot;Install&quot;. Immediately folder Fonts: created files &quot;arialregular.font&quot; and &quot;arialregular.otag&quot;, which are necessary in order to see the system font. Do the same steps if you wish for other fonts.


Final stages 

After completing the above, open the folder AROS: Prefs / and run the program settings Fonts. In the new window, select the fields &quot;Icons&quot; and &quot;Screen&quot; as the font &quot;ArialRegular&quot; to the size you want. In the field &quot;System&quot; to give &quot;s_courier&quot;, which, however, because it is not True Type Font support Antialising, and may seem a little broken. You can also use the CourierNew, if you have installed the above procedure. After you save the changes and open the Zune program settings. In this set the &quot;ArialRegular&quot; font fields in tabs &quot;Windows&quot; and &quot;Groups&quot;, and save the changes. Reboot the system. To make sure that the above worked properly run NoWinED, which you will find under the folder AROS: Tools /. If that everything is working correctly you will see the menu and the settings window with Greek letters. You can also write in the language using the button Alt. Second program that you can try, which is fully localized, is WookieChat, which you will find in the folder AROS: Extras / Networking. And in this place all the menu and settings window works. 


===Windows===

*Intuition
The window you position and resize, you right click on that windows title bar and in the dropdown menu you snapshot from there.  Right click to show menu -&gt; Window -&gt; Snapshot Windows or All but it will NOT work if that folder has no icon (e.g. Disk.nfo) attached to it. You need a folder icon. The window information gets saved in it.  

As for maximising the window using a shortcut key - Alt and up arrow key 

The AROS-Shell windows can be moved, resized by editing sys:s/icaros-sequence 

&lt;pre&gt;
; run shell
if ${Icaros/autoshell} EQ true
  run QUIET c:newshell &gt;NIL:
EndIF
&lt;/pre&gt;

; slimmer right aros the screen 
run QUIET c:newshell con:0/150//300/ &gt;NIL:

; top right corner scr-x scr-y win-x win-y
run QUIET c:newshell con:600/150//300/ &gt;NIL:


*Zune - AROS version of MUI
Magic Menu type functionality is implemented in IControl preferences editor: in the frame called Menus, switch type from Pull-Down to Pop-Up and/or iControl just tick the sticky menu option. 


Windows outside screens causing a problem either uncheck &quot;Offscreen move&quot; for windows in IControl prefs editor. Or use FKey commodity and define two key shortcuts: 

* the first using the command &quot;cycle windows&quot; (for example ALT TAB); 
* the second using the command &quot;rescue window&quot; (for example ALT F5). 

Now you can cycle windows until the one you want to rescue, and then &quot;rescue&quot; it: it will move back inside your screen. 


How to save the window size on wanderer (snapshot all, snapshot windows)

Same for icon position on wanderer, can't save the position. Icon position cannot be saved yet, but you should be able to save the window position and size. sys:prefs - wanderer icon has option to save window size on exit but just for dh0. To get saving working on (DH1: Extras:) partitions try deleting the dh1 disk.info file, then reboot. The system should create a new dh1 icon. 


* how to set up permanently 'view all files'?
As for viewing all files, removing disk.info for that disk did the job 

* how to list and kill processes (xkill would be useful) ? 
sys:Extras/System/Scout can kill apps 

sys:Tools/Commodities/Exchange can remove available commodities


* how to restore 'go up' button in wanderer window? (it doesn't show up anymore).
If you're using Icaros, go to the theme prefs and make sure that decoration is checked. Also, some themes do not use a parent button, so try another theme. You may have to restart Aros before the theme will change.

* Is it really safe to turn off (hardware button) computer at any time (worried about USB hard disk)
yes you can turn off the computer IF none of the drives are in progress (i.e. writing). Best to use Wanderer menu option Quit otherwise 


===Say narrator===

SPEAK: is a write-only DOS device for text-to-speech abbreviated as tts. 
To check if available, type assign into the shell and at the bottom in the Devices: section should be SPEAK 

Examples of use 
&lt;pre&gt;
Copy S:Startup-Sequence SPEAK:
Echo &quot;Hello&quot; &gt;SPEAK:M/R/S150/P110
Echo &quot;DH1 EH0 L OW1&quot; &gt;SPEAK:A1
&lt;/pre&gt;

Classic options are M/F, R/N, S&lt;rate&gt;, P&lt;pitch&gt;, O0/O1, A0/A1, and D0/D1. O1 recognizes lines beginning with OPT/ as option changes. A1 treats input as narrator phonemes.

Long options select a speech engine:

Echo &quot;Hello&quot; &gt;SPEAK:ENGINE=narrator/VOICE=female/STYLE=natural/LANGUAGE=en-US

Supported selectors are ENGINE=, VOICE=, STYLE=, and LANGUAGE=. Values are case-sensitive backend identifiers. ENGINE=DEFAULT selects the system default. Narrator-compatible selectors continue through the classic translator/narrator pair. Other engines use speech.device. Direct phonemes require a narrator-compatible selection.


===Printing===

This needs further drivers written, we have postscript and write to file support only 


*Postscript

Best to set Printer Prefs in the Prefs drawer to print-to-file or parallel/USB port 


Save document in postscript or convert picture/text to postscript 

Print using compatible [http://en.wikibooks.org/wiki/Aros/Platforms/AROS_USB_support#printer.class_-_PostScript_3_and_internal_ghostscript_drivers Ghostscript printer] or Postscript printer 


*GutenPrint

Some work has been done 

;There are no individual drivers yet for HP's Photosmart, EPSON's EPL, CANON's, Lexmark, CUPS PPD, etc. 


*printer is simply not accepting IPP connections at the moment.

Please try the following steps:

Open the printer web interface in a browser:

 http://192.168.1.x/

Look for the network or protocol settings.

Enable IPP / Internet Printing Protocol.

Make sure TCP port 631 is open/enabled.

Save the settings and reboot the printer if the web interface asks for it.

 ipp://192.168.1.xx:631/ipp/print

 ipp://192.168.1.xxx:631/ipp/


===Files===

====File endings and datatypes====

* Check if the file has his own .info icon file with a tool set to open it. IIRC this has higher priority over the def_XYZ.info file association. 
* In ENVARC:SYS/def_Text.info or whatever def_ file needs changing, use Wanderer's menu Icon -&gt; Information and change the def_XYZ.info there. If you're on ABIv0 and want it to be applied immediately, you might have to copy it to ENV:SYS/ (or to reboot). 
* Identifying file types by file ending is only a fallback. Far better it is to search for magic words, for flac files this would be &quot;flaC&quot; according to this [http://flac.sourceforge.net/documentation_format_overview.html documentation]. 

For instance, to open PDFs with arospdf not localised in the default drawer of Icaros (Work:Extras/Applications/arospdf) but localised in a custom drawer in AROS. The default tools are defined in the icons in sys:prefs/env-archive/sys e.g. def_PDF. 


File type identification is done by datatype descriptors which you can find in Devs/Datatypes. The AROS build system has a tool which creates such datatype descriptors. 


'''Changing of default tools of existing icons is easy as shown above. Adding of new file types is not hard, but needs knowledge of the AROS build system.'''


The enduser way would be to download the attached file, which contained two executables:
1) createdtdesc, to make a new datatype description
2) examinedtdesc, to read/show existing datatype descriptions

use 2 to get an idea on how it things are currently done in aros by providing this executable a file from the drawer sys:devs/datatypes/ (alternatively you can find the original .dtd files here).

use 1 to make your new datatype. Use the accompanied FORMAT file (also here) to read how to make your own datatype descriptor. use 2 to get hints from other datatype descriptors.

Note:
When creating a new descriptor would advise against using the pattern property, but instead use the default pattern of #? and create a Mask that matches your filetype. This requires some research in order to discover how your filetype can be recognized properly. Of course with making something like a descriptor for an ascii textfile, you would fallback to using the pattern (e.g. #?.text as the filetype cannot be determined easily otherwise). 

&lt;pre &gt;
# name - choose wisely and informative. also used for icon's name.
# version - choose as you like as long as it complies with version rules
# basename - the 'root' datatype class. be aware that e.g. it can influence behaviour. for example when choosing binary and using tool multiview in project icon, the file will be viewed as binary file (choosing sound would tell mulitview to view the file as a soundfile). So this can influence the underlying tool being used. Could become messy if users started to modify the tool manually. 
# pattern - This is the file pattern match e.g. #?.text
# Mask - A mask to identify the file. Requires knowledge of the actual file structure. For example 'M' 'Z' for an msdos executable.
# GroupdID - not supported (AROS native) files - use syst as that would be the least intrusive in case an AROS tool/program tries to load such datatyped file.
# ID - In your case, the first four characters of the name at subchapter 1 (in lower case) (or less if name is shorter).
# flags - How the mask needs to be interpreted. In your case would be mostly DTF_BINARY in combination with (wanted or not) DTF_CASE (to tell if mask used letters are case sensitive or not)
# priority - the priority of how the type is handled so that on datatype could have precedence over another? In any case, document tells it to be mostly 0. 
&lt;/pre &gt; 

Now that you know each field and what it does (more or less), you write this fields in a text file for your own invented datatype, save it and create the actual dt with the tool in 1. in the end the created dt must reside in sys:devs/datatypes/ drawer.

Then you would create a default icon in sys:prefs/Env-archive/SYS drawer. Don't forget to reboot or copy .info file to ram:env/sys in order to test. also don't forget to set which tool to start f.e. c:lx or dh4:emulators/mycoolemulator

To test, open Wanderer then show all files and doubleclick on a file of type you just created. Alternatively you could use the 'open' command from shell (with file of datatype you just created as parameter).

And as a last note. it would perhaps be welcome to have a program like xicon and/or runprglist for AROS (unfortunately both without source, but something similar could be created for AROS).

Sounds complicated ?

Perhaps... but OS like windows needs a complete registry to be able to do things like this. And yes, i am aware windows has gui tools that does it (more or less) for you (by manipulating the registry). Same could be done for AROS (without integrating a registry in AROS that is ).

Would that suffice ?

red1+2: typos, reformatting.

disclaimer: please note that using these tools can screw up your currently installed support for datatypes when used incorrectly. Do not use if you do not understand what you are doing. Use at own risk.


==Network Connection==

AROS currently only has one real choice for TCP/IP networking - AROSTCP.  This is a port of the AmiTCP package from AmigaOS (TM), with a number of enhancements/fixes from AROS developers. 


 Please use Prefs/Network to set up wired, wireless or USB networking 
 Non USB wifi is easier, USB wifi can be an annoyance - remember to save whilst in prefs 


===Wired===

=====IPv6=====

Some support 


128bit IPv6 address packet 
&lt;pre&gt;
Local FD::/8
Global 2000::/3
64:ff9b::/96
&lt;/pre&gt;
NAT64 translates IPv6 to IPv4 
DNS64 


OS routing works with 
&lt;pre&gt;
MacOS Ventura 
Windows 11 with cloud account 
Ubuntu Jammy Jellyfish 
Android 10 (block google dns) 
&lt;/pre&gt;


====IPv4====

The top half of the IPv4 Configuration tab on the Network Prefs deals with the network card/USB and the lower half the router part. 

[[File:AROS Wanderer Network Prefs DHCP.png|thumb|DHCP Settings]]

'''Upper part of IPv4 tab''' 
* Click Add on the top right of the Prefs which opens a window called '''Interface''' 
* Enter Name as net0 (but can be anything as long as it is consistently used in other sections) 
* check mark on Active
* select device to be used using the '''right hand-side gadget''' of the box where the device name will go 
* set Unit to 0 
* IP Mode is default set to '''Get address from DHCP''' 


* IP Mode set to Manual if DHCP does not work automatically 

From the shell CLI,  ifconfig -a

Under net0: section, inet starting 192.168.x.xxx

* inet or '''Address''' of network card 
* netmask convert to decimal so 0x'''ffffff7f''' becomes 255.255.255.247 which is used to adjust the above '''Address''' into 
* broadcast 192.168.xxx.xxx

click OK


[[File:AROS Wanderer Network Prefs Manual.png|thumb|Manual Settings]]

'''Lower part of IPv4 tab''' 
* IP Mode Get address from DHCP (default) 


* or changing to Manual if automatic DHCP set up does not work 
* '''Gateway''' (Router Internal LAN-IP) (Default Route) = 192.168.0.1 (D-Link Netgear), 192.168.1.1 (Linksys 3com), 192.168.2.1 (SMC Microsoft), 192.168.1.254 (Belkin), 192.168.123.254 (USRobotics) else check with your router manual 
* first DNS = use 208.67.222.222 (opendns) or Gateway number above (to test web browser access to router) or 212.50.160.100 (google)  i.e. or whatever your ISP needs you to set 
* second DNS = use 208.67.220.220 (opendns) or Gateway number above (to test web browser access to router) or 213.249.130.100 (google) i.e. or whatever your ISP needs you to set 


* At the bottom of IPv4 tab, check mark the '''Start networking during system boot''' option 
* Save and reboot (sometimes Network restart fails, so reboot every time to be sure) 


'''an alternative way''' to AROS ifconfig -a, other OSs have similar for the same internet connection. Another connection will have different settings. 

e.g. From [http://www.ncsu.edu/resnet/windows/ipconfig/ Windows], '''ipconfig /all''' 
and note down the IP, subnet mask, default gateway, and DNS servers values and put these values in &quot;manually&quot; into AROS Network prefs. 

e.g. From Linux via dhcp router have a look at etc./dhcpc/dhcpcd-eth0.info 
* for manual input look at /etc/networks (IP or Gateway) and /etc/resolv.conf (DNS) 

 Please note that all in one routers (wired+wireless) or separate routers may need different settings 

IPv4 involves routing (192,168.x.x), firewall, NAT 


===Wireless===

[[File:MyArosWirelessSetup.png|thumb|Setting up]]

[[File:MyArosWirelessTCP.png|thumb|Shell commands to work out what is happening]]

We must first make certain you have a Atheros 5k chip inside acting as the wireless wifi option. Open PCITool in Tools directory. Down left hand side are a series of numbers 0.00.0 etc. Click on some at the bottom and hopefully one of them will say Atheros AR5??? or AR242?. 

or a Realtek RTL8187B, we can check using Prefs/Trident as this one is USB based 


There are many similarities with the above Wired set up so please read the above section as well 


* open Network/Prefs
* In '''IPv4 Configuration''' tab - click Add - enter net0 / active tick / #?.device / Unit 0 / IP Mode = manual (important if default DHCP does not work automatically) 

Make sure that any extra network names (e.g. eth1 or net1) should be deleted. If net0 already st previously, change net0 so that it shows associated with the appropriate device name like atheros5000.device or realtek8180.device. Having two entries here will cause sub-net problems. 

* Go to '''Wireless''' tab and click on &quot;Add&quot; button. 
* Insert network name (SSID your wireless network name use wirelessmanager to get it), select right &quot;encyption&quot; that is most likely &quot;WPA&quot;. 
* Key Type set as &quot;Passphrase&quot;. i.e. type in your password for your router (aka access key). 
* Unselect (no tick) &quot;hidden&quot; if it is selected, then apply. You may have to tick it if wireless does not work. 
* Finally, Save and '''reboot'''. 

For the best chance of success, set networking to start at boot, and then reboot with the USB adapter plugged in. 


===USB Ethernet===

Open SYS:Prefs/Network and in the IPv4 Configuration tag (top table covers your usb stick) 

* click Add button
* set Name as net0
* Tick Active box
* enter the usb-ethernet.device e.g. dm9601eth.device, usbpegasus.device or usbasixeth.device use SYS:c/devlist, '''Scout''' or trident prefs to get the correct spelling 
* set Unit to 0 (which is usual but check the messages from the bottom of the Trident prefs whilst plugging the device in to determine the unit number otherwise) 
* IP Mode is set to Get address from DHCP (make sure your router is set right for that) 
'''or manual'''
* IP Address of network card, i.e. 192.168.0.xx or 192.168.1.xx (xx being greater than 1) 
* Subnet netmask = 255.255.255.0 
* click OK

There can be sometimes be boot failures when using USB ethernet - plug the USB device in after boot and save the network prefs to make it work again. 


Lower part of IPv4 tab covers the router information 

* IP Mode Get address from DHCP 
'''or if manual settings'''
* Gateway (IP Address of router) = usually 192.168.0.1 or 192.168.1.1 but see router manual to make sure. 
* first DNS = use 8.8.8.8, 208.67.222.222 (opendns) or 212.50.160.100 
* second DNS = use 8.8.4.4, 208.67.220.220 (opendns) or 213.249.130.100 


===USB Tethering via Android smartphone===


Go to AROS Network Prefs (IPv4 configuration tab) and write type in &quot;usbrndis.device&quot; in the &quot;device&quot; textfield of &quot;Interface&quot; sub-window, which appears when you add a new device (or modify an existing one). Select &quot;Start Network during system boot&quot; and saved the configuration, the Connection is immediate no reboot is needed.&lt;br&gt;

usbrndis.device is a resident device (virtually always there) in fact, a driver is not present in DEVS:Networks &lt;br&gt;&lt;br&gt;

Plug in USB cable, go to Android settings and enable &quot;USB Tethering&quot; &lt;br&gt;

A reboot should not be necessary.

When restarting AROS, the Smartphone deactivates the connection and to access the network again have to reactivate it before starting the browser. 


===Solving Issues===

[[File:MyArosTCP.png|thumb|Aros network setup diagnostics - why does it not work?]]

* In Network Preferences, have '''only one''' item in the IPv4 Configuration tab 
* If using manual settings, make sure all numbers are correct, especially for IP address of the card/usb (changing the last number in chain of four) 
* For any USB based networking, it is often necessary to save in Prefs/Network, reboot AROS and network support can begin 


* For wired, make sure that the LAN-cable is plugged in before starting the computer 


* If wireless, try getting closer to the router. 
* Switch off the encryption option from your router then try wifi, if successful then your ip/dns is ok. If not then your ip/dns settings are most probably wrong or need to use one or more opendns numbers 
* Replace detachable wireless antenna (best wireless option to buy if you can) with a stronger antenna ie. 5&amp;nbsp;dBi or 7&amp;nbsp;dBi 
* Try with another computer/laptop/machine 

Program Error  C:WirelessManager 

* Test with another OS 
* Check that Wifi works before changeover (if possible) 
* Check that socket and card are working 
* Check if card is too new for laptop (date code on card MMYY blue askey date 2005-2007 etc)   


Are you connecting with the Router ? 

Check with protection off e.g. wps and wep to see if it makes a difference. 


For USB wireless - stopping and starting may be needed...

&lt;pre&gt;

; $VER: AROSTCP-startnet 1.0 (01/08/06)
; AROSTCP-startnet (c) The AROS Dev Team.
;
Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

; stop and restart
execute &quot;sys:system/network/AROSTCP/s/stopnet&quot;

Run &lt;NIL: &gt;NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
  ; echo &quot;Stack online&quot;
Else
  echo &quot;Wait for Stack Failed&quot;
EndIf

run &lt;NIL: &gt;NIL: wirelessmanager realtek8180.device

&lt;/pre&gt;


What IRQ number is assigned to the device? You can check with Tools/PCITool? 
It's possible the BIOS hasn't set the right IRQ number. If you have a Linux CD/DVD handy, could you check if it boots with the options &quot;acpi=off noapic nolapic&quot;? 


If the following does nothing, this will help us figure out why networking doesn't start automatically at boot

open a shell and run the following commands:

&lt;pre&gt;
echo ${AROSTCP/AutoRun}
echo ${AROSTCP/WirelessAutoRun}
echo ${AROSTCP/WirelessDevice}
&lt;/pre&gt;

Please report the output, typically it will look like this  

# True  (explanation this variable is related to the &quot;Start networking during system boot&quot; checkbox in network prefs) 
# True  ()
# Devs:networks/atheros5000.device unit 0


If there's a problem with the AROSTCP package. What's the output of this?

 ENV:sys/packages/AROSTCP 

should return a string = Sys:System/Network/AROSTCP


By the way, a quicker way to check networking is working would be to run some shell commands such as:


&lt;pre&gt;
ping www.google.com
ifconfig net0
&lt;/pre&gt;


The best way to list the available networks and diagnose / troubleshoot problems with connecting to a wireless network is to run WirelessManager manually. First uncheck the &quot;Start networking during system boot&quot; box in the Network prefs app, then save and reboot. Then run this in a shell:

 C:wirelessmanager atheros5000.device verbose 

or 

 C:wirelessmanager realtek8180.device verbose 

and capture the output 


If the above does not help, could you edit the file SYS:System/Network/AROSTCP/S/Package-Startup, and change &quot;&gt;NIL:&quot; to &quot;&gt;T:wifi.log&quot; on the WirelessManager line and add this as well Wait 5?

&lt;pre&gt;
if ${AROSTCP/WirelessAutoRun} eq &quot;True&quot;
Run QUIET &quot;C:WirelessManager ${AROSTCP/WirelessDevice} &gt;T:wifi.log&quot;
wait 5
EndIf
&lt;/pre&gt;

Then save, reboot and post the log file (T:wifi.log) here.


&lt;pre&gt;

c:wirelessmanager atheros5000.device verbose
Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7)
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'


Then it just sits there. Not sure what a normal dump looks like, I don't see anything that looks wrong in the configuration.
&lt;/pre&gt;

looks like the driver isn't working with that card. Has anyone else successfully used that exact model number (AR2413)?


&lt;pre&gt;

Initializing interface 'atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=7):
65 63 68 65 6c 6f 6e echelon
PSK (ASCII passphrase) - hexdump_ascii(len=14): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='echelon'
*** [wpa_sm_init] sm-&gt;pmksa=02c66fd4 ***
Own MAC address: 00:01:36:15:ae:0c
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
Added interface atheros5000.device:0
State: DISCONNECTED -&gt; SCANNING
Started AP scan for wildcard SSID
MLME: starting scan
MLME: scan channel 1 (2412 MHz)
sana2: sending MLME frame


Then it stops. Does this mean the router is not authorizing this NIC?

IRQ 4 (A)

&lt;/pre&gt;

apparently locking up when the first frame is sent (a scan request).


&lt;pre&gt;

Devs/Networks/atheros5000.device:0
Initializing interface 'Devs/Networks/atheros5000.device:0' conf 'ENV:Wireless.prefs' driver 'default' ctrl_interface 'N/A' bridge 'N/A'
Configuration file 'ENV:Wireless.prefs' -&gt; 'ENV:Wireless.prefs'
Reading configuration file 'ENV:Wireless.prefs'
Line: 1 - start of a new network block
ssid - hexdump_ascii(len=12):
41 69 72 4c 69 6e 6b 35 39 33 30 30 AirLink59300
PSK (ASCII passphrase) - hexdump_ascii(len=8): [REMOVED]
key_mgmt: 0x2
PSK (from passphrase) - hexdump(len=32): [REMOVED]
Priority group 0
id=0 ssid='AirLink59300'
*** [wpa_sm_init] sm-&gt;pmksa=0224e444 ***
Own MAC address: 00:1f:e1:42:e3:7a
RSN: flushing PMKID list in the driver
Setting scan request: 0 sec 100000 usec
[eloop_reg_timeout] Timeout is at 1317686594.160000
EAPOL: SUPP_PAE entering state DISCONNECTED
EAPOL: Supplicant port status: Unauthorized
EAPOL: KEY_RX entering state NO_KEY_RECEIVE
EAPOL: SUPP_BE entering state INITIALIZE
EAP: EAP entering state DISABLED
EAPOL: Supplicant port status: Unauthorized
EAPOL: Supplicant port status: Unauthorized
[eloop_reg_timeout] Timeout is at 1317686595.060000
[eloop_reg_timeout] Timeout is at 1317686604.060000
Added interface Devs/Networks/atheros5000.device:0
[eloop_run] Starting
State: DISCONNECTED -&gt; SCANNING
Starting AP scan for wildcard SSID
MLME: starting scan
[eloop_reg_timeout] Timeout is at 1317686594.160001
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.233000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.373000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.513000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.553000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.693000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686594.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686594.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.013000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.073000
EAPOL: disable timer tick
EAPOL: Supplicant port status: Unauthorized
MLME: scan channel 14 (2484 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.113000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.153000
MLME: scan channel 1 (2412 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.193000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.213000
MLME: scan channel 2 (2417 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.253000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.293000
MLME: scan channel 3 (2422 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.333000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.353000
MLME: scan channel 4 (2427 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.393000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.433000
MLME: scan channel 5 (2432 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.473000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.493000
MLME: scan channel 6 (2437 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.533000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.573000
MLME: scan channel 7 (2442 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.613000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.653000
MLME: scan channel 8 (2447 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.673000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.713000
MLME: scan channel 9 (2452 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.753000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.793000
MLME: scan channel 10 (2457 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.833000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.853000
MLME: scan channel 11 (2462 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.893000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.933000
MLME: scan channel 12 (2467 MHz)
[eloop_reg_timeout] Timeout is at 1317686595.973000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686595.993000
MLME: scan channel 13 (2472 MHz)
[eloop_reg_timeout] Timeout is at 1317686596.033000
sana2: sending MLME frame
[eloop_reg_timeout] Timeout is at 1317686596.073000
MLME: scan completed

&lt;/pre&gt;

Is your network hidden? If so, did you enable the 'Hidden' checkbox in the network prefs? What distro version are you using? 


&lt;pre&gt;
&quot;ENV:sys/wireless.prefs&quot; looks like this:
network={
ssid=&quot;testadhoc&quot;
key_mgmt=NONE
wep_key0=&quot;12345&quot;
wep_tx_keyidx=0
}
&lt;/pre&gt; 


If your router doesn't broadcast its SSID (hidden), you need to add this option to the network block of the wpa_supplicant.conf on your aros machine and make changes after  # Example blocks: 

 scan_ssid=1

Here's a full description of all the [http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/wpa_supplicant.conf config file options]. 

&lt;pre&gt;
ap_scan=1

network={
ssid=&quot;YOURESSID&quot;
scan_ssid=1
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
group=CCMP
psk=YOURPASSWORD
}
&lt;/pre&gt;

&lt;pre&gt;
filter_ssids=1
ap_scan=2

network={
ssid=&quot;REMOVED&quot;
scan_ssid=1
bssid=REMOVED
priority=100
mode=0
proto=RSN
key_mgmt=WPA-PSK
auth_alg=OPEN
pairwise=CCMP
group=CCMP
psk=REMOVED
}
&lt;/pre&gt;


Error 6: Couldn't resolve host name.

Check Scout -&gt; Devices and look at the device that you are using, in the OCnt column it should state 2 which means AROSTCP and Wirelessmanager are both accessing this driver. If 0 or 1, then uncheck the checkbox in Network prefs for starting networking at boot, save and reboot. Then run this is the shell:

C:WirelessManager realtek8180.device unit 0


some quirks setting up the wireless network as well 

1) it's far better setting up either the wired OR the wireless network adapter as net0:, or weird things happen

2) it's better using fixed IP on the local network instead of DHCP

3) network setting must be placed in network setting panel in /prefs, using the wirelessmanager helped me finding available SSIDs, but not actually connecting to them

once done, reboot.


If previous setup is proving problematic 

&lt;pre &gt;

SYS:Prefs/Env-Archive/Wireless.prefs
SYS:Prefs/Env-Archive/Zune/OWB.config
SYS:Prefs/Env-Archive/Zune/global.config
SYS:Prefs/Env-Archive/AROSTCP/WirelessDevice
SYS:Prefs/Env-Archive/AROSTCP/db/Interfaces
&lt;/pre &gt; 

Make a copy of these files and restore in case of problems. 


Please try this test to check if you can connect to your router, ie established that the WiFi layer is working 

̊̊̊̊Boot with networking disabled, by make sure that &quot;Start networking at boot&quot; in Network Prefs is unchecked (no tick).  
̊ Run this in a shell: C:WirelessManager atheros5000.device VERBOSE
̊If the output of that command is too long to summarise here, you can redirect it to a file by adding &gt;RAM:wifi.log to the end, then attach or paste that file here.


try running &quot;status&quot; in the shell and check that AROSTCP is listed/running
If AROStcp is not showing, then AROSTCP is not running. attempted to start it by clicking Use or Save in network prefs, or checking the &quot;start networking at boot&quot; box or typing into a shell. 

 Execute SYS:System/Network/AROSTCP/s/startnet

(run Status again afterwards).


The &quot;cannot resolve hostname&quot; will appear if you are blocked on the wifi network by the router as well as aros not being able to assign correct network address.

One way of testing this might be to disable the firewall in the router. you might also check the router how it sees the attempts aros do to speak to it. The easiest way to do that would be to manually give aros an IP number in the routers accepted range. and see if it shows up at all within the router.


Tests that can be undertaken to determine correct settings and functions 

 pciinfo
 sanautil -d broadcom4400.device status

&lt;pre &gt;
 ping &lt;router-address&gt; e.g. 192.168.0.1 (aka inet) or 80.237.146.33 (www.amiganews.de) 
 ifconfig net0
 ifconfig net0 up
 extras:networking/utils/sanautil/sanautil -d atheros5000.device status
 WirelessManager atheros5000.device verbose &gt;RAM:wifi.log
 ;to send the log to RAM disk to be read easier or if detected, 
 Run WirelessManager atheros5000.device &gt;NIL:
 Run WirelessManager atheros5000.device ssid=&quot;mynet1&quot; &gt;NIL: 
 C:WirelessManager realtek8180.device unit 0 
&lt;/pre &gt; 

Please look at the task list in Scout, and check if WirelessManager and AROSTCP are running. Also look at the device list in Scout to check if realtek8180.device is open. 


start tools/debug/sashimi, maybe it shows some debug messages when disconnection happens.


Firstly, let's take a look at what your setup most likely looks like, assuming you use a router. See diagram below: 

&lt;pre&gt;
Internet &lt;---------&gt; home router &lt;---------&gt; computer 
-----------external IP------------------internal IP-------------
&lt;/pre&gt;

Okay, so what am I trying to show you with that diagram. A few things. Firstly, the IP address that connects you to the Internet is not the same one that connects you to your router. What happens is that your computer doesn't have a direct connection to the Internet, instead your router connects to the Internet, and your computer connects to the router.

You can see the external and internal IP addresses in these example settings...

* Default Gateway : 76.91.64.1 (external IP for ISP/Internet host)
* IP Address : 76.91.71.184 (external IP for home router)

* IP Address : 192.168.0.1 (internal IP for home router)
* Address = 192.168.0.161 (internal IP for computer)

As you can see, there are two internal IP addresses and two external IP addresses. This is because there is a client/server relationship, effectively one address is for the service (server) and one address is for the device trying to access that service (client).

The server addresses in your case are 76.91.64.1 (your ISP's address, serving the Internet), and 192.168.0.1 (your home router's address, serving your home network). The term gateway applies here, they are your gateway to those services.

Subnet masks are used along with IP addresses to determine which IP addresses are allowed access to a network. I did learn the more in-depth rules about subnet masks once (watched a CCNA vid), but I've forgotten about it. The basic level of understanding you'll need is easy to remember though. A subnet mask value of 255 means that portion of the IP address must stay constant, whereas a subnet value of 0 means any unassigned value up to 255 is allowed in the IP address.

By far the most common subnet value is 255.255.255.0. What this means is that the first three parts of the IP address you use to connect to a service must stay the same as the server/gateway address, and only the last section can change.

So if your router's internal IP address is 192.168.0.1, and the subnet mask is 255.255.255.0, the only addresses that will be allowed to be used on that network are between 192.168.0.2 and 192.168.0.255 (I think 192.168.0.0 is reserved for other uses).

Final point to make is about DHCP (a.k.a. dynamic IP) vs static IP. A server/router using DHCP gives a device that connects to it an address within the acceptable range. It usually starts with the lowest numbered free address, so with your router it'll give the first device that connects to it 192.168.0.2, the next device 192.168.0.3, and so on. Static IP addresses are where you set the IP address you want to connect with in advance. 

When using static IP addresses on a router where DHCP is active, it's good to use a high number to avoid conflicts with other devices that are connected to your network, to reduce the risk that both devices will try using the same IP. That's why your current choice of 192.168.0.161 is good, unless you have over 159 devices connected on your current network!


Okay, so what's the next step. Well, if you can use ping, I'd suggest pinging 192.168.0.1. If you get a positive response it means you're connected to your router, if you don't get a response it means the connection between your router and your computer is at fault.

Documentation on configuring the AROSTCP environment further can be found [http://en.wikibooks.org/wiki/Aros/User/Networking here] 


===File Sharing===

As AROS knows only a few filesystems (FFS, OFS, SFS, PFS (amiga only), FAT12, 16, 32, Microsoft NTFS (windows), UDF (Blu-ray)). 
The others in regular use like MacOSX hfs+, Linux ext2/ext3 and ext4, Haiku BeFS provide a problem in transferring files. 

Linux can access SFS partitions but it needs to be compiled. The latest full source are [http://home.elka.pw.edu.pl/~mszyprow/programy/asfs/ here]. It compiled fine with a 2.6.30 kernel in Puppy Linux 4.31. 

An alternative, is to use a FAT32 partition to share. Setup a 4G FAT32 partition using HDToolbox for sharing, and the rest of the space as SFS for an Aros install. It works very well. 

Files could be transferred via TCP internet network. 


====SMB2/3====

With Windows you can share one folder or all folders of the &quot;Public&quot; user.

On Windows what is important is to enable sharing (Network and Sharing Center).

AROS Mountlist should look lke this 
&lt;pre&gt;
Handler = L:smb2-handler
StackSize = 65536
Priority = 5
GlobVec = -1
ACTIVATE=1
Startup = &quot;smb://UserAcc:password@PCShare/Sharefolder&quot;
&lt;/pre&gt;

which could also be
&quot;smb://UserPC:password@192.168.x.x/Public&quot;
or
&quot;smb://UserPC:password@Name-PC/Public&quot;

so
&quot;smb://UserPC:password@192.168.1.158/Folder&quot;
or
&quot;smb://UserPC:password@Name-PC/Folder&quot;


After you have configured a share generates a DOSDrivers it is named &quot;SMB0&quot; which includes the setting, and at each reboot it is Mounted. You can still delete the DOSDriver by hand, is located in Storage/DOSDrivers, the file &quot;ServerAutoMounts&quot;, in ENV:AROSTCP which indicates the DOSDriver to be mounted, should also be deleted. 
The per-mount files are written to ENV:SMB or SYS:Storage/DOSDrivers. There is also additional file ENV:AROSTCP/ServerAutoMounts which states what will be presented to the end user. 


====Old SMBFS====

e.g. to connect to a NAS share such as \\NASBOX\Shared use -:

SMBFS WORKGROUP=&lt;YOUR WORKGROUP NAME&gt; VOLUME=&lt;AROS volume name to use&gt;: SERVICE=&lt;UNC Path to connect to&gt;

SMBFS WORKGROUP=MYNET VOLUME=Shared: SERVICE=//NASBOX/Shared

And you will then have an icon appear on your desktop for the volume name you have chosen. 


You can put the above script into wbstartup or  

give it an icon, change it to a 'project' and give it the default tool c:iconx 

Open a shell and type copy sys:script.info &quot;sys:wbstartup/YOURSCRIPTNAME.info&quot;

This should create an icon for your script file.

Now right-click on your script and select 'information'.

Change 'tool' to 'project', put 'c:iconx' into the 'default tool' box, click save 

The reason being that scripts need to be opened with 'execute SCRIPTNAME' (or 'iconx') whereas the programs started from wbstartup are opened using 'run PROGRAMNAME'. It's the same as trying to start a command-line tool from the workbench by double-clicking it.


====Setup ISO images within AROS====

Use [http://archives.aros-exec.org/index.php?function=browse&amp;cat=driver/storage DiskImage] which supports many cd image formats ISO, CCD, MDF/MDS, CUE/BIN, NRG and UIF. To mount CD or DVD images use below....

&lt;pre &gt;
# Rename your iso 'Unit0' (note no extension).
# Do 'View/All files' on you Aros partition. You should now see a folder called 'Diskimages'. Copy your renamed iso to there. 
(Alternatively, you could type at the shell 'assign FDSK: xxx', where xxx is the location of your iso.) 
# From the shell, type 'mount CD0:' and the iso should appear on the Wanderer desktop. You can now access it like a real disk.
&lt;/pre &gt; 

 assign devname: dismount 
 Assign DOSVOLUME: remove
 [http://aminet.net/package/disk/misc/unmount-0.1 unmount] most filesystems work but SFS lacks support for ACTION_DIE packet 

If you are using an IcAros install, the startup scripts are set up to wipe the Diskimages directory on boot, so its worth keeping a second copy of the iso somewhere else. Alternatively, you could set up extra mountlists for additional iso images. I've made a file called iso1 in the Aros:devs directory that contains the following text:

&lt;pre&gt;
/* Entry for ISO image */

ISO1:
FileSystem = cdrom.handler
Device = fdsk.device
Unit = 1
LowCyl = 0
HighCyl = 0
Surfaces = 1
BlocksPerTrack = 1
DOSType = 0x41434400
Activate = 1
#
&lt;/pre&gt;

Then I just need an iso called 'Unit1' (corresponding to the 'Unit = 1' entry in the mountlist) in Diskimages (or wherever I assign FDSK: to) and to mount I type in at the shell:

 Mount iso1: from devs:iso1

Of course, if you create mountlists for ISO2, ISO3:, etc. (with the corresponding change to the 'Unit = ' line) you can have as many isos mounted as you wish. I just call mine ISO1: etc. to distinguish them from the real CD drives 


==Video Guides==


Video demonstrations and tutorials covering:

:00. '''Introduction''' 
::[https://www.youtube.com/@jamesmattson6813/videos Various Aros Installs], 
::[https://www.youtube.com/embed/j8EmSEby0Rg AROS repo in gource, view of AROS dev commits from 1997 to 2025], [http://www.youtube.com/watch?v=Vx_zqlBow40&amp;feature=related Gource view of AROS 1997 up to 2009], 
::[http://www.youtube.com/watch?v=s1RsvEm7UrU Why an Amiga OS in 2011], 
::[https://www.youtube.com/watch?v=1W886mheV74&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Johan Grip on early days of AROS x86], [https://www.youtube.com/watch?v=mXaKDhtTTqQ&amp;t=14s&amp;pp=ygUPYW1pZ2EgYXJvcyAyMDI2 Michel Schulz on Aros and PiStorm], 

:01. '''Installation'''
::[https://www.youtube.com/watch?v=M7YjufrJqDs Aros One install], [https://www.youtube.com/watch?v=iIMguHTdC5E Aros One USB install], [https://www.youtube.com/watch?v=ZNXauy5m5Wc Aros One install], [http://vimeo.com/11013489 Modify Grub boot], 
::[http://www.youtube.com/watch?v=wyQVeyXIywc&amp;feature=channel iMica Silent Pt3], [http://www.youtube.com/watch?v=o2AnkoflY14 Wipe whole drive and Install - warning loss of data on drive], 
::[http://www.youtube.com/watch?v=OVXm6_-witQ VirtualBox install], [ VMware install], 
::[http://www.youtube.com/watch?v=0k2PEmT8I14 Broadway AROS Install], 
::[https://www.youtube.com/watch?v=PtDiXhjSIfs Is Aros Icaros a choice?], 
::[ driver install], 
::[http://www.vimeo.com/10491104 HDAudio install but needs account], [], 

:02. '''Amiga Basics'''
::[http://www.youtube.com/watch?v=TY8mWxwzH5o Screens tutorial], 
::[https://m.youtube.com/user/AMIGASYSTEM/videos General], [ Dos Scripts tutorial], [http://www.youtube.com/watch?v=hPT7SmVEpjc OS 1.2], [http://www.youtube.com/watch?v=n6kX3FqH8Ww&amp;feature=related OS 1.3], 

:03. '''Customisation demos'''
::[https://www.youtube.com/@AMIGASYSTEM/videos Prefs tutorial], [ Decoration tutorial], [http://www.youtube.com/watch?v=Dn5C8G3aDXU Scalos], 

:04. '''Setting up''' internet access and surfing the web, FTP, IRC and Mail apps 
::[ Network Prefs], [ AirCOS tutorial], [ jabberwocky tutorial], 

:05. '''Native bundled Games and Applications''' 
::[http://www.youtube.com/watch?v=aYlFv2B-VXc 3D Games], [http://www.youtube.com/watch?v=MXK7wwhd-R0 Latest Games], [http://www.youtube.com/watch?v=RUgiVThv23Q&amp;feature=mfu_in_order&amp;list=UL PrBoom GL], [http://www.youtube.com/watch?v=0s7u8TPy7V4 Assault Cubes], [http://www.youtube.com/watch?v=fih6aCXKeqs Cube 2], [http://www.youtube.com/watch?v=-X0ay0MGOms DosBox on Aros], [http://www.youtube.com/watch?v=7nKduDjf14k Oct 2010], 

::[http://www.youtube.com/watch?v=FziV2z_uxnQ Apps Pt 1], [http://www.youtube.com/watch?v=xs37_nfa5CI Apps Pt 2], [http://www.youtube.com/watch?v=Bn59_VvbQR0&amp;feature=related Apps Pt 3], 
::DOpus4 [http://www.youtube.com/watch?v=aSRybWjrrME DOpus 4], 
::Milkytracker [http://www.youtube.com/watch?v=VxBOEPzpdKg&amp;feature=related Laying Down Base Tracks], 
::[http://www.youtube.com/watch?v=k2uKQ0-ieOE Audio Evolution 4 in action], [http://www.youtube.com/watch?v=Zq4r9k0_jZI Quick Videos], 
::[http://www.youtube.com/watch?v=gGKCFZcIc0I&amp;feature=related ScreenRecorder], [http://www.youtube.com/watch?v=974c2e-Fqak&amp;feature=related TV out Tests], 
::[http://www.youtube.com/watch?v=fjq8ct5d5IY AmiFIG], [http://www.youtube.com/watch?v=h0rHvPhYJo4&amp;feature=youtu.be ZuneFIG], 
::[http://wiki.povray.org/content/Documentation:Tutorial_Section_1 POVray Tutorial 1], 
::[http://www.youtube.com/watch?v=Jk-ZNLfJsvQ pt 1, jan. 2008], [http://www.youtube.com/watch?v=nWRy33g1R7Y pt 2, feb. 2009], [http://www.youtube.com/watch?v=r5PbhCtm4vE pt 3, feb. 2010], 

::[https://www.youtube.com/watch?v=G7_FJUoQ89o Hollywood programming], [], [], [],

::[], [], [], 
::[], [], [], 
::[], [], [], 


:06. '''Commercial software available'''
::[http://www.youtube.com/watch?v=fKXY9B4R43s AntiryadGX 3D Game Editor], 
::[http://www.youtube.com/watch?v=TMS9NDzwm5U BOH indie Game], 

:07. '''Running classic amiga apps and games''' 
:: Amiberry [], [], 
::[http://vmwaros.blogspot.com/2008/11/introducing-amibridge.html Intro Amibridge], [http://www.youtube.com/watch?v=ee2PWvCZeLo Old Amiga Apps], [http://www.youtube.com/watch?v=ee2PWvCZeLo Why Janus UAE is good], 
::[https://www.youtube.com/watch?v=VhlsNSYSuDg DPaint tutorial]

::[http://vmwaros.blogspot.com/2009/11/can-icaros-play-my-amiga-games-and-why.html Play Amiga Games], [https://www.youtube.com/watch?v=XTaZCNOvCnE], 
::[http://www.youtube.com/watch?v=tMehS77LXQ4 Pagestream Introduction], [http://www.youtube.com/watch?v=284-w3hTzII Pagestream Tutorial 1], [http://www.youtube.com/watch?v=mlwEGwhZzl4 Pagestream Tutorial 2], 
::[http://www.youtube.com/watch?v=iIcrIjPOctc Catweasel Mk4 PCI Part 1] and [http://www.youtube.com/watch?v=BaitHeL6bEA Part 2], 

:08. '''Misc and History'''

::[http://www.youtube.com/watch?v=d6mDXKU29w0 Mum uses old AmigaOS Workbench 1.1 (1986)], [http://www.youtube.com/watch?v=DaRkacQ-YMg Why an Amiga 500 (1987)], [http://www.youtube.com/watch?v=k5CYsgVCzYY an Amiga 2000 (1987)], 

:09. '''Misc Shows and Events'''
::[http://www.youtube.com/watch?v=klgVSWKs4kE VCF 2010], [https://www.youtube.com/watch?v=eQ3d5qR-Hv8 24:06 Jason McMullan at amiwest 2012 about AROS], [https://www.youtube.com/watch?v=jpQO7XSfAv4 Aros SMP multi core amiwest 2013], [], [https://www.youtube.com/watch?v=gFRtAAmiFbE], [https://www.youtube.com/watch?v=DjdUEyjx8GM], [https://www.youtube.com/watch?v=ydYDqZQpim8], [], [https://www.youtube.com/@uminekoshouten/featured], [https://www.youtube.com/shorts/NfoY023w-vE], 

:10. 
::[https://www.youtube.com/shorts/6qJTNW4-6GY]


===History===

The project was originally started by a small group of Amiga [http://www.amigahistory.co.uk/aros.html enthusiasts] in 1995. These individuals were mainly computer-based college university students at the start, though that student trend has diminished since. An interview with Aaron Digulla [http://arosshow.blogspot.com/2006/12/interview-with-aaron-digulla-who.html here] 

* 1992 Commodore folds 
* 1996-1998 much of the early years was concerned with exec, dos and intuition libraries. 
* Early 1999, Haage &amp; Partner used parts of the AROS code in AmigaOS 3.9. 
* March 2001, floppy disk images of AROS became available. 
* Early 2002, AROS changed its name from Amiga Replacement Operating System to Amiga Research Operating System 
* June 2002, AROS devs decided to use Zune (MUI 3.8 rewrite) as the GUI system. 
* November 2002, Eric Schwartz drew Kitty for AROS usage. 
* Early 2003, AROS.org underwent a graphics facelift. 
* Late 2003, GCC C compiler arrived. 
* Early 2004, Aros-Exec opened. 
* Early 2005, Aros Max bootable CD arrived. 
* Late 2005, SFS filesystem ported and allowed fast access to apps and network support arrived 
* Early 2007, AROS.org underwent another graphics facelift. 
* Mid-2007, AROS changed to AROS Research Operating System after A.Inc. sued Hyperion with a trademark violation. 
* Late 2007, the hard disk installer added and VmwAROS (later called Icaros Desktop) distro launched. 
* Early 2009, Our first usable web browser (OWB)
* September 2010, first wireless support appears and AspireOS started as a distro 


* Early 2012, the first paper-cut bugfix and Fab's Odyssey Web Browser ported 
* Early 2017, work started on utilising the addition cores on modern CPUs starting with the 64bit x86 PC version  
* Mid-2017, m68k port optimized for the Vampire 2 / Apollo accelerators (68080 AMMX FPGA) 
* 2018 The old AROS Exec website closed and a new one opened 
* 2019 AROS One x86 32bit distribution started and now with USB install version 
* Early 2021, backport of more features of 32bit PC ABIv1 into 32bit PC ABIv0 (Aros One 1.5 and above) 
* 2025 year of 64bit pc builds and porting 32bit applications to 64bit ABIv11
* 2026 update of [https://www.youtube.com/watch?v=6FKTL068ULM&amp;pp=ygUPYXJvcyBhbWlnYSAyMDI2 nvidia nouveau driver for 64bit PC] 


===Bounties===

To help inspire developers with both ideas and monetary incentives, rewards are offered for the successful completion of &quot;bounties&quot; (requests for missing/new functionality) chosen by the community and handled by [http://power2people.org power2people] (formerly done by TeamAROS). A monthly option is [http://www.power2people.org/funds/aros/ here].


Future goals for AROS include expanding its underlying retargetability to support even more diverse architectures, provide memory protection features and user level file security, SMP and many other wonderful features missing from AmigaOS &amp;mdash; while still providing as much source level compatibility as is possible (however it is accepted that to achieve some goals code certain things may require a little recoding).


[http://www.ohloh.net/p/aros/contributors Developers] come and go as with any open source effort and we would like to thank them for their efforts... 

;1996-2000:In DigullaA (coordinator), GripJ, TempletonI (BSD), SchulzM, RittauS, voordenDagL, HolmM, JohanssonT, VanIngelgomH, SteigerwaldM, BortasP, deJongK, AlfredssonJ, InnocentiB, 

;2001-2005:In [http://chodorowski.com/adam/aros.html ChodorowskiA], StegerG, BergerS, HeutlingS, AlemagnaF (gcc), VerhaegenS (rexx), KielH, MatheussenKS (CAMD), SzczygielskiP, ErikssonP, LeCorfecD (Zune), BauerS (Zune), FurlongW, GustafssonJ, AndrewsN, CafferkeyN, GierichM (jpeg), PattonJ, ParsonsM, DietrichJ, SeilerT, BischoffL, LorentzenNH, AdamO, BerglundH, SmithP, HolmenD, BlomM, 

;2006-2010:In FedinP, RusslerM, SzymczykS (owb), SmiechowiczK (openGL), WeissM, NorrisR, BrunnerO, WiszkowskiT, GreppinA, [http://www.fukt.bsnet.se/~bearsoft/ Bearsoft Björn Screwelius], ErbY, CharletF, HodgesC, [http://aros-exec.org/modules/newbb/viewtopic.php?topic_id=4819&amp;forum=18&amp;post_id=43103#forumpost43103 HokstadV], McMullanJ (m68k), WilenT (m68k), 

;2011- :In MuijzenbergPHvanden, ALB42, JonesEM, weiju, DizzyofCRN, wawa, miker, 


* 1996 - The linux hosted version for i386 was the first to arrive 
* 1998 - i386, The native version for i386-based PC AT computers and compatibles.
* 2004 - x86/64, The native version for 64-bit (x86_64, amd64) PC computers.
* 2008 - sam440/ppc, The native version for Sam440EP, Sam440EP Flex and Sam460ex computers.
* 2009 - efika, The native version for PowerPC Efika computers.
* 2010 - m68k, The native version for m68k Amigas or WinUAE
* 2013 - raspi/armfh, early native version for ARMv6 based Raspberry Pi computers.
* 2017 - x86/64bit smp 


Debugging capture serial debug at all (especially with sysdebug=all or --sysdebug=all) to see it displayed on screen 

* yes, usb -&gt; rs232 adapters can work most of the time, some of the cheapest ones are not fully compatible with all rs232 devices to capture to another device 
* you will need a null modem cable (or a null modem adapter usually female to female) in addition to the usb -&gt; rs232 adapter (usb adapter is a normal modem ie. the pins are not crossed over) 

Normal modem cable - straight connection DCE 
&lt;pre&gt;
Pin 2 -&gt; Pin 2  RXD
Pin 3 -&gt; Pin 3  TXD 
Pin 5 -&gt; Pin 5  GND
&lt;/pre&gt;

Null modem cable connections DTE 
&lt;pre&gt;
Pin 2 -&gt; Pin 3
Pin 3 -&gt; Pin 2
Pin 5 -&gt; Pin 5
&lt;/pre&gt;
(9pole SUB-D)


&lt;pre&gt;
serial  ser: (amiga/aros)  tty2 tty1USB0 (linux)  COM1 (windows)  (depends on the os being used) 
speed baud transfer rate 9600 38400     lower baud might be more successful 
data bits 8
stop bits 1
parity none
handshaking flow control - none xon/xoff (most likely)  rts/cts  dsr/dtr (pins not connected so should not work) 
&lt;/pre&gt;


*You cannot use compiled aros X86-64 bit software (when ready) on aros X86 32bit. PPC compiled software on X86 and so on. 
*68k is tested with the UAE emulator (WinUAE) but some tests are done on native 68000 based Amigas and others. 
*PPC support is very limited to certain devices. 


If you use the WBStartup, you have to delete the other icons in the folder (readme etc..) and you have to add in the Icon Tooltype the parameter DONOTWAIT

If you use user-startup instead, you need to add the attached command &quot;after assignment to LUA&quot;
C:WBRun DH1:Extras/Utility/WeatherBar/WeatherBar &gt;NIL:
Change the command to match your WeatherBar path.

&lt;pre&gt;
PATH sys:Utilities/WeatherBar ADD
run &gt;nil: lua:amilua weatherforecast.lua
&lt;/pre&gt;

To enter data your Country or City, ist with city_id numbers can be found [http://bulk.openweathermap.org/sample/city.list.json.gz here] or you need to go to [https://www.bbc.com/weather BBC Weather], once you type the name of your city or town in the appropriate tab, and press enter, the 7 numbers to be added in the &quot;WeatherBar&quot; will appear on the Browser url address bar above 


Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251 – Cyrillic (Amiga)
    ISO-8859-1 – Western European
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2 – Central/East European
    ISO-8859-3 – South European
    ISO-8859-4 – North European
    ISO-8859-5 – Slavic languages
    ISO-8859-9 – Turkish
    ISO-8859-15 – West European II
    ISO-8859-16 – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)
&lt;/pre&gt;


Icaros 2.3 USB image needs a header stripped so it can work correctly 
 dd bs=512 skip=1 status=progress if=icaros_light_2-3-0_pendrive.bin of=/dev/sdxy &amp;&amp; sync


Scalos 
&lt;pre&gt;
-------------------------------
{ &quot;STRING&quot;,		&quot;ID/K,TEXT/K,SRC/K,TEXTPEN/K,HALIGN/K,STYLE/K,FONT/K,VALIGN/K&quot;,

HALIGN		LEFT | CENTER | RIGHT

VALIGN		TOP | CENTER | BOTTOM

STYLE		NORMAL | BOLD | ITALIC | BOLDITALIC

FONT		// font specification - format: &quot;fontname.font/size&quot;

-------------------------------
arguments for STRING SRC

&quot;diskstate&quot;,		
&quot;diskusage&quot;,		
&quot;diskusagefree&quot;,	
&quot;diskusageinuse&quot;,	
&quot;diskusagepercent&quot;,	
&quot;fibfilename&quot;,	
&quot;filecomment&quot;,	
&quot;filedate&quot;,		
&quot;fileprotection&quot;,	
&quot;filesize&quot;,		
&quot;filetime&quot;,		
&quot;filetypestring&quot;,	
&quot;iconname&quot;,		
&quot;linktarget&quot;,		
&quot;plugin&quot;	pluginname &lt;optional plugin arguments&gt;
&quot;versionstring&quot;,	
&quot;volumecreateddate&quot;,	
&quot;volumecreatedtime&quot;,	
&quot;volumeordevicename&quot;,	

-------------------------------

arguments for HIDE

&quot;novolumenode&quot;,	
&quot;isempty&quot; (some STRING)	

-------------------------------

all internal commands:

&quot;about&quot;,		
&quot;backdrop&quot;,		
&quot;cleanup&quot;,		
&quot;cleanupbyname&quot;,	
&quot;cleanupbydate&quot;,	
&quot;cleanupbysize&quot;,	
&quot;cleanupbytype&quot;,	
&quot;clearselection&quot;,	
&quot;clone&quot;,		
&quot;close&quot;,		
&quot;copy&quot;,		
&quot;cut&quot;,		
&quot;delete&quot;,		
&quot;emptytrashcan&quot;,	
&quot;executecommand&quot;,	
&quot;formatdisk&quot;,		
&quot;iconify&quot;,		
&quot;iconinfo&quot;,		
&quot;lastmsg&quot;,		
&quot;leaveout&quot;,		
&quot;makedir&quot;,		
&quot;open&quot;,		
&quot;parent&quot;,		
&quot;paste&quot;,		
&quot;putaway&quot;,		
&quot;quit&quot;,		
&quot;redraw&quot;,		
&quot;redrawall&quot;,		
&quot;rename&quot;,		
&quot;reset&quot;,		
&quot;selectall&quot;,		
&quot;showallfiles&quot;,	
&quot;showonlyicons&quot;,	
&quot;shutdown&quot;,		
&quot;sizetofit&quot;,		
&quot;snapshot&quot;,		
&quot;snapshotall&quot;,	
&quot;snapshotwindow&quot;,	
&quot;unsnapshot&quot;,		
&quot;update&quot;,		
&quot;updateall&quot;,		
&quot;viewbydate&quot;,		
&quot;viewbyicon&quot;,		
&quot;viewbysize&quot;,		
&quot;viewbytype&quot;,		
&quot;viewbytext&quot;,		
&lt;/pre&gt;


{{status|50%}}
{{BookCat}}</text>
      <sha1>4049m7avrdihn4o2tj84x93251nkstk</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/Developer/Docs</title>
    <ns>0</ns>
    <id>13107</id>
    <revision>
      <id>4669752</id>
      <parentid>4669714</parentid>
      <timestamp>2026-09-12T12:17:40Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669752</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129118" sha1="rpmmi25njmcf3558cpnm95s7uz9fo6e" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the gimmearos.sh script (on [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/cross aros-archives]) to setup the developer environment by downloading necessary packages ...
The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://aros.sourceforge.net/documentation/developers/compiling.php More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/jamiepine/voicebox voicebox]
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]
*[ Chatterbox TTS]
*[ Index TTS] 
*[ Qwen 3.5 TTS]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 

 Coding 
*[ gpt-oss-20b 4Q] smaller 
*[ Qwen3-coder-next] larger 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>rpmmi25njmcf3558cpnm95s7uz9fo6e</sha1>
    </revision>
    <revision>
      <id>4669753</id>
      <parentid>4669752</parentid>
      <timestamp>2026-09-12T12:18:34Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669753</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129129" sha1="sn15nofhsiw3cqbqskch641cjp02wie" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the gimmearos.sh script (on [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/cross aros-archives]) to setup the developer environment by downloading necessary packages ...
The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://aros.sourceforge.net/documentation/developers/compiling.php More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/jamiepine/voicebox voicebox]
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]
*[ Chatterbox TTS]
*[ Index TTS] 
*[ Qwen3 TTS]
*[ Omnivoice]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 

 Coding 
*[ gpt-oss-20b 4Q] smaller 
*[ Qwen3-coder-next] larger 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>sn15nofhsiw3cqbqskch641cjp02wie</sha1>
    </revision>
    <revision>
      <id>4669754</id>
      <parentid>4669753</parentid>
      <timestamp>2026-09-12T12:21:45Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669754</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129159" sha1="hjmbp7uxdvgdmuixyn5r85b3xw77jb0" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the gimmearos.sh script (on [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/cross aros-archives]) to setup the developer environment by downloading necessary packages ...
The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://aros.sourceforge.net/documentation/developers/compiling.php More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox TTS]
*[ Index TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ fasterqwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 

 Coding 
*[ gpt-oss-20b 4Q] smaller 
*[ Qwen3-coder-next] larger 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>hjmbp7uxdvgdmuixyn5r85b3xw77jb0</sha1>
    </revision>
    <revision>
      <id>4669755</id>
      <parentid>4669754</parentid>
      <timestamp>2026-09-12T12:27:39Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669755</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129117" sha1="hp9pp4arbonzuclrha5hh7u0rcel608" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the gimmearos.sh script (on [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/cross aros-archives]) to setup the developer environment by downloading necessary packages ...
The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://aros.sourceforge.net/documentation/developers/compiling.php More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox]
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>hp9pp4arbonzuclrha5hh7u0rcel608</sha1>
    </revision>
    <revision>
      <id>4669756</id>
      <parentid>4669755</parentid>
      <timestamp>2026-09-12T12:33:29Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669756</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129140" sha1="8f8174163q0yekim8jqbkp1lmnioknv" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the gimmearos.sh script (on [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/cross aros-archives]) to setup the developer environment by downloading necessary packages ...
The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://aros.sourceforge.net/documentation/developers/compiling.php More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>8f8174163q0yekim8jqbkp1lmnioknv</sha1>
    </revision>
    <revision>
      <id>4669770</id>
      <parentid>4669756</parentid>
      <timestamp>2026-09-12T16:35:24Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669770</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129119" sha1="8kcqjjp08j34t7hyuihb5gxfyspvjjk" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/cross gimmearos.sh script] to setup the developer environment by downloading necessary packages ...  The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://http://developers.aros.org/documentation/compiling.html More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>8kcqjjp08j34t7hyuihb5gxfyspvjjk</sha1>
    </revision>
    <revision>
      <id>4669772</id>
      <parentid>4669770</parentid>
      <timestamp>2026-09-12T17:03:59Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669772</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129166" sha1="fpll8tvenc73nqun2cm89sujqflo7k6" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/cross gimmearos.sh script] to setup the developer environment by downloading necessary packages ...  The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://http://developers.aros.org/documentation/compiling.html More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes) and context length (you set Gbytes taken) - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>fpll8tvenc73nqun2cm89sujqflo7k6</sha1>
    </revision>
    <revision>
      <id>4669777</id>
      <parentid>4669772</parentid>
      <timestamp>2026-09-12T18:14:57Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669777</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129176" sha1="k68mrarkz59mfgizst3ffuwajdzaohd" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/cross gimmearos.sh script] to setup the developer environment by downloading necessary packages ...  The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://http://developers.aros.org/documentation/compiling.html More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes), context length (you set Gbytes taken) and KV cache - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>k68mrarkz59mfgizst3ffuwajdzaohd</sha1>
    </revision>
    <revision>
      <id>4669778</id>
      <parentid>4669777</parentid>
      <timestamp>2026-09-12T18:24:47Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669778</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129203" sha1="kwdx1i4aoq8kqc3jst7r4fnx7dhlw6m" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/cross gimmearos.sh script] to setup the developer environment by downloading necessary packages ...  The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://http://developers.aros.org/documentation/compiling.html More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
*DGX Spark   about 220Gb/s
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes), context length (you set Gbytes taken) and KV cache - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

*[ gpt-oss-120b] 70Gb model  

Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] for larger machines 
*[ Qwen-3.6-27B] for larger machines 
*[ Qwen 3.5 9B Q4] for lesser machines 
*[ Qwen 2.5 14b Coder] for smaller machines 
*[ gpt-oss-20b 4Q] smaller 

*[HauHau 3.6 35B] 

*[ muse-glimmer]


Small models 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>kwdx1i4aoq8kqc3jst7r4fnx7dhlw6m</sha1>
    </revision>
    <revision>
      <id>4669831</id>
      <parentid>4669778</parentid>
      <timestamp>2026-09-13T06:37:32Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669831</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129164" sha1="fpgkgpjra6qamnhneluycw6ekyfkvw9" xml:space="preserve">{{ArosNav}}

==A technical overview of AROS==

Google translation [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=de&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs German], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=fr&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs French], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=it&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Italian], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=es&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Spanish], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=hi&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Hindi], [http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=zh-CN&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fwiki%2FAros%2FDeveloper%2FDocs Chinese], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=ru&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Russian], 
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pl&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Polish],
[http://translate.google.com/translate?hl=en&amp;sl=auto&amp;tl=pt&amp;u=http%3A%2F%2Fen.wikibooks.org%2Fw%2Findex.php%3Ftitle%3DAros%2FDeveloper%2FDocs Portuguese]

{{Uncited}}

AROS,&lt;ref&gt;[http://aros.sourceforge.net/download.php References and sources]&lt;/ref&gt; like AmigaOS (TM), is a [[w:Message passing|message-passing]], [[w:Preemption (computing)|preemptive]] [[w:Multitasking|multitasking]] [[w:Operating system|OS]].

It uses [[w:Reentrant (subroutine)|re-entrant]] shared libraries to save memory space.

AROS is based around an executive library kernel (Exec) and two other libraries:

* Exec (the &quot;kernel&quot;, which is not a kernel in the modern sense), 
* Intuition (graphics and GUI, integrated into the system) and 
* AmigaDOS (Disk Operating System, the Metacomco's Tripos modified to work with Exec).

The design philosophies of AmigaDOS and Intuition are rather different, the former adopting a C-like API and the latter creating an [http://www.basden.demon.co.uk/amiga/amiga.oo.html object-oriented], message passing aware environment for the programmer. The system base is the only absolute address in AmigaOS (located at 0x00000004) this does differ with AROS as AROS SysBase is automatically provided (no $4) but everything else is dynamically loaded. The OS is well known for delivering high performance due to its close connections with the hardware, while simultaneously having the flexibility to support re-targetable graphics (Cybergraphics) and retargetable audio subsystems (AHI).

: Diagram showing relationships of libraries to system needed


Remember, AROS is a [http://en.wikibooks.org/wiki/Aros/Developer/ABIv1 research] operating system, and while all contributions to the base AROS code are welcome, please contact the dev list first for any core changes. Writing applications for AROS does not have this requirement. 

While AROS appears and feels almost feature complete, it is still [[Aros/Developer/IncompleteAPIs|missing a small number of functions]] from the Amiga API. 


[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1201 This thread provides] information for setup, [http://www.aros.org/documentation/developers/index.php documentation] and whether you are interested in core OS changes and/or writing/porting software apps 

*you compile directly under AROS, which can be running on either real hardware, virtual hardware
*in hosted mode under linux/window, cross-compile from that host OS (save your files as ISO-8859-15 encoding instead of UTF-8) [https://github.com/BlitterStudio/aros-compiler-docker Docker images] 


'''The repository''' for 64bit and 32bit ABIv1 all hardware platforms is [https://github.com/aros-development-team/AROS current development version]. 
There are many forks of this so that developers can work on their own and forward changes at a later date as discussed on the dev forum 


64bit PC is one of two hardware platform with another fork called [https://github.com/deadwood2/AROS abiv11] which is used for Aros One x64 PC 

32bit PC is the other fork [https://github.com/deadw00d/AROS/tree/alt-abiv0 repository for current stable PC version ABIv0 with backported ABIv1 features is located which is used on AROS One and Icaros x86 32bit based distros] this is for historic reasons 


Any [https://github.com/aros-development-team/AROS/issues bugs / issues can be added for ABIv1 issues]. The two individual PC forks have their own issues tab on their github webpages 

We have a [https://arosdevteam.slack.com/archives/CUFV48U3H slack here], discord on [https://discord.gg/UKp9qdEBuQ Discord@AmigaDev], 


==Software Development for AROS==

===Programming languages===

====Common to all====

'The Developer Environment', which primarily supports C/C++ code, there are other scripting programming languages available 

:[[Aros/User/DOS|DOS]] 
:[[Aros/Developer/Docs/LUA|LUA]] 
:REXX [[Aros/Developer/Docs/Rexx|Regina (AROS' ARexx)]] 


====Needs to be compiled/ported====

::[[Aros/Developer/Docs/LLVM|LLVM]] 
::Python [ Info], [], 
::[https://ae.arosworld.org/index.php?board=11.0 FreePascal FPC Aros-Exec thread], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language fpc arm here is very old and will not work], FreePascal for AROS has its own [http://fpcaroswiki.alb42.de/ Wikibook], 


::[http://sourceforge.net/projects/xamos/ X-Amos Basic] 
::[http://sdlbasic.sourceforge.net/ SDLBasic] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[[Aros/Developer/Basic/Basic4SDL|Basic4SDL]] ([https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language ])
::[http://alvyn.sourceforge.net/ Alvyn] ([http://www.dusabledanslherbe.eu/AROSPage/MISC.14.html download]) 


::[http://www.airsoftsoftwair.com/ Hollywood when enough users warrant a port - paid one time fee language] 


::[[Aros/Developer/Docs/E|AmigaE Portable E]]


====Hardware Restricted====

'''Basic'''

:[http://amos.pspuae.com/AmosProManual/contents/c1.html '''Amos Pro'''] [http://amos.pspuae.com/index.php?action=forum#1 compatible] [http://www.amigacoding.com/index.php/Main_Page commands] (all incomplete) 

:'''Blitz Basic''' [http://aros-exec.org/modules/newbb/viewtopic.php?post_id=46537#forumpost46537 none on AROS] 
:: [http://www.amiforce.de/main.php Amiblitz] on amiga(TM) emulator

:'''Amiga Basic'''
:: [ ACEBasic]

'''Misc''' 
:Ruby [http://www.ruby-lang.org/en Info]/[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Ruby 32bit PC], 


===Where to get the C/C++ Environment===

If you want to develop for AROS, its generally easier to be running linux hosted AROS development environment especially for C++, cross compiling the code. That's how most developers now are doing it. g++ is used to compile owb web browser as well as some other AROS software. If you were hoping for a rich set of C++ libraries or classes defined for the OS feature set, you might be disappointed.

AROS Native compiling is possible, but you're much more likely to run into the odd bug(s) in the dev environment since it gets little testing and fixing by other developers.

Is there a sftp software or scp over ssh available?
Maybe. At least the security part would be handled by [https://github.com/jens-maus/amissl amissl] [https://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc port]. [https://github.com/BlitterStudio/dopus5 DOpus5] has recently added sftp support. See here for a [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1974&amp;highlight=ssh&amp;pid=12073#post_12073 ssh scp client]

[https://arosdevteam.slack.com/join/shared_invite/enQtOTc4Mzg0NDIzNzQ0LWQ2NWZmNmMwNGIwNGEyNTgxNzU3MGFjMTk3ZThmOTQ1MTVjMzhmNTllYWQ0ZTUxMjBjMGE0Y2VjMDJmNTc5MzI#/shared-invite/email Slack Dev Forum] 


====Cross compilers from Windows or Linux====

*Windows WSL2 walkthrough can be [https://arosnews.github.io/how-to-cross-compile-aros-hosted-wsl/ found here] 


you want to build AROS. No problem.

Here are instructions for PC 64-bit:
https://github.com/deadw00d/AROS/blob/master/INSTALL.md

Here are instructions for PC 32-bit:
https://github.com/deadw00d/AROS/blob/alt-abiv0/INSTALL.md

And as always has been the case you can use the contrib archive to 'obtain' the development directory which contains the /native/ AROS gcc compiler and tools. That compiler is used to build AROS itself but can be used outside the AROS build process by providing --sysroot with indicated directory to cross compile for AROS.


'''64 bit'''


'''32 bit'''

A good option for multiple OS is [https://axrt.org/index.php?tab=download-aros AxRuntime lets developers compile their Amiga API-based applications as Linux binaries being able to utilize modern development tools available on Linux, like IDEs, debuggers, profilers, etc] 


Older 32bit guides for Linux hosted compiler

Please install these packages before moving to next step. Below is a reference list for Debian-based distributions. Reference build system was Ubuntu 18.04/20.04 amd64.

subversion git-core gcc g++ make gawk bison flex bzip2 netpbm autoconf automake libx11-dev libxext-dev libc6-dev liblzo2-dev libxxf86vm-dev libpng-dev gcc-multilib libsdl1.2-dev byacc python-mako libxcursor-dev cmake zsh mingw64

Do all of these operations under home directory of your user or another directory where your user has write permissions.

Specifically, in a section &quot;Linux-i386&quot;, be sure first to build the cross-compiler (toolchain-alt-abiv0-i386) and only then AROS itself (alt-abiv0-linux-i386).


Clone &amp; build
&lt;pre&gt;
$ mkdir myrepo
$ cd myrepo
$ git clone https://github.com/deadw00d/AROS.git AROS
$ cd AROS
$ git checkout alt-abiv0
$ cd ..
$ cp ./AROS/scripts/rebuild.sh .
$ ./rebuild.sh
&lt;/pre&gt;

Now to the build selection below - Linux-i386 

Select toolchain-alt-abiv0-i386 - Select alt-abiv0-linux-i386 (DEBUG) 

Start AROS by:
&lt;pre&gt;
$ cd alt-abiv0-linux-i386/bin/linux-i386/AROS
$ ./Arch/linux/AROSBootstrap
&lt;/pre&gt;


Pc-i386 Select toolchain-alt-abiv0-i386 (if not built yet) - Select alt-abiv0-pc-i386

ISO image available in alt-abiv0-pc-i386/distfiles


Now that we have linux-hosted build, we can resume native (option 2).
Run ./rebuild.sh and selection option 2. Wait until it finished, then:
&lt;pre&gt;
$ cd alt-abiv0-pc-i386
$ make
&lt;/pre&gt;

Now
&lt;pre&gt;
$ make bootiso
&lt;/pre&gt;


Now, your compiler is located in toolchain-alt-abiv0-i386 directory and named i386-aros-gcc. Includes are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/include and libraries are in alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development.lib.

This is how then can be passed to the compiler:

/home/xxx/toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot /home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development -L/home/xxx/alt-abiv0-linux-i386-d/bin/linux-i386/AROS/Development/lib 

../toolchain-alt-abiv0-i386/i386-aros-gcc --sysroot bin/linux-i386/AROS/Development local/helloworld/helloworld.c -o local/helloworld/helloworld


Another method was using Debian like distros and download the [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/cross gimmearos.sh script] to setup the developer environment by downloading necessary packages ...  The gimmearos script is a good start in that direction, building the cross compilers and hosted AROS environment, but gimmearos.sh might be out of date or not be completely compatible with any given linux distro. 

In order to do that, you have to compile AROS yourself. Download AROS source archive not contrib. Compile AROS by entering the main directory

 ./configure
 make

([http://http://developers.aros.org/documentation/compiling.html More on compiling AROS]). The result will be a basic AROS system without development tools.

To compile C++ on Linux, type 'make gnu-contrib-crosstools', creating the cross-compilers in ./bin/linux-i386/tools/, named i386-aros-gcc, etc.

'''Note''': Currently, to make the cross compilers usable copy 'collect-aros' from tools/ to tools/i386-aros/bin/. At the moment the cross compilers if used from the Linux command line will only find it when it's there.

If you want to compile native compilers (the Developer Environment), type 'make contrib-gnu-gcc', creating native compilers in AROS' System:Development/bin directory.

When the output needs to be stripped &lt;code&gt;--strip-unneeded --remove-section .comment&lt;/code&gt;

The Obj-C backend should build out of the box.

Open contrib/gnu/gcc/mmakefile.src and search for the line which contains &quot;--enable-languages&quot; and add &quot;objc&quot; to the list of languages that follows it.

    --enable-languages=c,c++,objc

Better make it—enable-languages=c,c++,objc,obj-c++

ObjC++ is broken as soon as you try to use exceptions, but that might change in future GCC versions and it does not hurt having it there already.


Do you need a cross-compiler or a real compiler? In the first case you can get away with just downloading the proper gcc archive, apply the patch and proceed with the normal gcc build. In the case of a real cross-compiler then when downloading the contrib sources, also need to download the normal sources, place the contrib sources into a directory called contrib, need to install autoconf+automake+perl+python, call ./configure, cd into the subdirectory and type make.

to rebuild GCC with host == build == target == i386-pc-aros. So just get the vanilla sources and apply the patches without bothering about the build system?


[https://vmwaros.blogspot.com/2019/10/a-pre-configured-development-machine.html pre-configured VM environment vmware virtual machine to develop AROS and AROS software]


====Native compilers for AROS====

Namely gcc for C or g++ for C++ are supplied with the [[Aros/Developer/Docs#The Developer Environment|Developer Environment]], which is already '''setup''' and part of any current AROS distribution like AROS One or the nightlies 

* Current GCC 6.5 (32bit) though moving to 10.5 and 15.1 (64bit) 
* Older software components. GNU GCC 4.x GNU BinUtils, GNU Fileutils 4.x, GNU Textutils and others usually deprecated 

On single partition systems and the Boot ISO, the AROS Developer environment is installed under &quot;SYS:Development/&quot;. Systems with multiple partitions - such as a Work: partition - tend to install it to there instead, however it can be installed manually to any location. Please remember, if moving, that you will need to correct the Development packages 'install location' env variable to point to the new locations root - look in SYS:S/startup-sequence.

&lt;pre&gt;
Assign Development: SYS:Development 
Assign C: Development:bin ADD 
&lt;/pre&gt;


In the aros build instructions. you need to check out contrib and/or ports into your AROS source directory, as subdirs. then, assuming you are building in an external build dir, as you should, you simply configure and &quot;make contrib&quot; for instance or whatever submodule you might want to build.


===Beginners Tutorials in C C++===

As AROS is [http://eab.abime.net/showthread.php?t=29856 C based] API compatible to AmigaOS 3.x, so most of the information on programming C on the Amiga applies to AROS as well. Please note that there is a lot of AmigaOS 1.3 (1985-1989) and [https://www.markround.com/amigaguide AmigaOS AOS 2.x (1990-1992)] information around but OS3.1 is recommended but limited in amount. 

Brief overview of what is required to write AROS Applications

# Using [[Aros/Developer/Docs/Libraries/Intuition|Intuition]] for basic screens/windows 
# Using graphics within windows via 8bit [[Aros/Developer/Docs/Libraries/Graphics|graphics]] and so onto  15-16-24bit [[Aros/Developer/Docs/Libraries/CGFX|cybergraphx]]
# Load and save work to [[Aros/Developer/Docs/Libraries/DOS|dos]] disk drives
# Using the [[Aros/Developer/Zune|ZUNE GUI Environment]]


Writing native games require this extra information

# Using [[Aros/Developer/AHIDrivers|AHI audio hardware independent API]]
# Using USB joystick/joypad with the Poseidon USB stack through [[Aros/Developer/Docs/Libraries/LowLevel|LowLevel]] library


Additional features that could be added later

# Adding additional [[Aros/Developer/Docs/Libraries/Locale|Locale]] language translations to your program 
# Adding a [[Aros/Developer/Docs/Rexx|AREXX/Regina]] port to your application 
# Executing Amiga(TM) [[Aros/User/DOS|DOS]] commands from your application
# Using [[Aros/Developer/Docs/Libraries/Icon|icons]] (.info files) and icon tooltypes (stack, version, and program startup options)
# Local couch or IP based SANA2 networking co-op multi player gaming support 


Most AmigaOS programming books are nowadays very much out of date as most are from the late 1980s and do not cover later amigaOS releases like 3.1 for example, Rob Peck's book &quot;Programmer's Guide to the Amiga&quot;. The Amiga ROM Kernel manuals aka RKMs like Libraries (3rd edition), Devices (), the AmigaDOS manual (3rd edition) and the Style Guide may have their uses. There are some reference examples from AmigaMail and Devcon notes (available again on an Amiga developers CD 2.1). 

For Arexx then &quot;The Amiga Programmer's Guide to ARexx&quot; by Eric Giguere, which was published by Commodore is useful as well as an &quot;Arexx Cookbook&quot;.


* Beginners C Guide [http://www.iu.hio.no/~mark/CTutorial/CTutorial.html C Tutorial], 
* [http://www.pjhutchison.org/tutorial/amiga_c.html Amiga based but interesting]
* [http://thecguru.com/ C for beginners],
* [http://fresh2refresh.com/c/c-basic-program/ C programming basics] for students, 
* [https://www.edx.org/courses Free Online course] from American Universities 
* Reference Amiga [http://amigadev.elowar.com/ API reference].


* AROS based c source can be found [[Aros/Developer/Docs/Examples|here]] and lots of example code can be found inside [https://github.com/aros-development-team AROS sources] themselves and from the contrib section of the archives from [https://github.com/aros-development-team/contrib Aros site], and study the AROS applications source code, e.g. the test programs from the Tests drawer (folder/directory). Take a look at the code of some smaller AROS programs might be a better and more up to date 

When you upload your builds, please write the architecture (like i386-aros, x86_64-aros, aarch64-aros etc.) in the archive name 
and it is also advisable to write in the field &quot;Requirements&quot; the ABI (ABIv1 leave blank, for PC fork 64bit ABIv11 ends in v11, 32bit ends in , Arm Pi ends ) 


===Compiling C/C++ Code===

Native, although we have a IDE Integrated Development Environment (Murks), it does lack a debugger. Whilst others use a combination of a text editor and shell to edit code. Most though use an AROS hosted on Linux to take advantage of the better GCC tools like GDB and various IDEs.

Open shell - its a menu option at the top left of Wanderer (desktop). Or by using the right Win key and w (or F12 and w) within the directory with the source code. Type in
 sh 
to change the amiga shell into a unix shell. You can then type in ls (unix equivalent to amiga dir). Take a look [http://en.wikibooks.org/wiki/Linux_commands here] for more commands.

For a single file program-name.c or program-name.cpp
 gcc -o program-name program-name.c  
or 
 g++ -o program-name program-name.cpp
or
 g++ -o test -Wall -g main.cc texturelib.cpp xmodelib.cc -lsdl -lgl

To close the shell, click on the top left-hand corner to close (twice). Once to get back the aros shell and then again to close finally. Use [http://freshmeat.net/projects/cksfv/ cksfv] as a test.

Some source code requires the addition of Amiga API libraries, like dos, which you can flag at the compile time as 
 gcc -o julia.exe julia.c -ldos

For DOS use -ldos as example and if you are compiling mui codes it will be -lmui or intuition -lintuition. Other missing symbols are due to linker libraries being necessary for linking in functions that aren't in the standard C libraries. For example some source code would need added

 -lz or -lm or -lpng or -larosc etc.

use this in unix line command mode to search for 'search-item' in many .c files (*.cpp for c++, etc.)
 grep -l 'search-item' *.c

If the program is not executable, try using parameter fno-common 

&quot;Delete #?.o&quot;? Or if you are using abcshell then &quot;rm *.o&quot;


:''More information: [[Aros/Developer/Porting software]]''


=== How to make Apps have AROS 64-bit specific support code ===

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

AROS64 already uses 64bit addressing, it just doesn't setup the MMU for more than 4GB physical memory currently.
When porting software to AROS64 it is &quot;mostly&quot; a case of converting ULONG's that are used to store pointers, into IPTR's instead, etc. Another quirk, is making sure items on the stack are the correct size by using the STACKED attribute for them. 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.

compiling mui stuff for aros setting -std=gnu99 is necessary, had -std=c99 usually 
A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order.

crash which suggest memory corruption. From my experience porting from 32-bit to 64-bit these kinds of errors can happen if a pointer is passed somewhere via ULONG variable. Then half of the pointer is cut.

To generate this error, please run AROSBootstrap with -m 1024. This will allocate heap to 64-bit address space which will make these errors immediatelly visible. These types of crashes are hard to debug. Disabled as little code as possible to stop corruption from occurring and then try to read from the code where it can be broken

Crashing in tslf_freevec is another symptom of memory corruption and these memory corruptions will manifest differently on different setups.


==Coding conventions==

As the AROS core source is a shared developer experience, there are rules regarding structure and style. When it comes to your creating your own app and coding, the structure and style should be your own, i.e. you should enjoy what you do and do it so that you can understand what is going on.

===Layout===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
static void 1st_function()
{
    program
    exit(0);    
}

int main(void)
{
    1st_function();
    2nd_function();
    3rd_function();
    return 0;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;

struct Screen * openscreen(void);
struct Window *openwindow(struct Screen *screen, const char *title, LONG x, LONG y, LONG w, LONG h);

VOID 1st_function();
VOID 2nd_function();

int main(int argc, char **argv)
{
    program
    return 0;
} /* main */

VOID 1st_function()
{

}

VOID 2nd_function()
{

}
&lt;/syntaxhighlight&gt;

===General style===

This code is used by many people and therefore you should keep some things in mind when you submit source code:

* Keep things simple 
* Keep the source clean 
* Always know what you are doing, if not flag it and describe what needs to be done... 
* Explain clearly/simply what you are doing 
* Remember that you write code once but that it is read many times by many people

===Comments===

AROS uses some of the comments in the source to generate the documentation. Therefore it's necessary to keep a certain format so the tools can find their information. Other comments are ignored but they should explain what you thought when you wrote the code. If you really can't think of an explanation, then don't write the code a second time like this:

&lt;pre&gt;
/* This adds 1 to t */
t ++;
&lt;/pre&gt;

What we think of is this:

&lt;pre&gt;
/* Go on with next element */
t ++;
&lt;/pre&gt;

===Formatting===

This is only '''IMPORTANT''' if you are going to work on the core AROS code or contrib but not applications which may reside outside like on AROS Archives or other websites.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
{
    /* a */
    struct RastPort * rp;
    int               a;

    /* b */
    rp = NULL;
    a  = 1;

    /* c */
    if (a == 1)
        printf (&quot;Init worked\n&quot;);

    /* d */
    if
    (
        !(rp = Get_a_pointer_to_the_RastPort
            (
                some
                , long
                , arguments
            )
        )
    ||
        a &lt;= 0
    )
    {
        printf (&quot;Something failed\n&quot;);
        return FAIL;
    }

    /* e */
    a = printf (&quot;My RastPort is %p, a=%d\n&quot;
        , rp
        , a
    );

    return OK;
}
&lt;/syntaxhighlight&gt;

Looks ugly, eh ? :-) Ok, here are the rules:

&lt;pre&gt;
If several lines contain similar code, put similar things below each other (see a and b);
Put spaces between operands and operators
Put braces {}, brackets [] and parentheses () below each other (d) if there is much code between. 
Brackets and parentheses may be in one line if the code between is small (c)
Indent by 4 Spaces. Two indent levels may be abbreviated by one tab.
&lt;/pre&gt;

'''Before committing please normalize the indentation - if you have a mixture of tabs and spaced - please always use spaces, 1 tab = 4 spaces.'''

The reasons for this are:

# While some editors can use an arbitrary sizes for tabs, it's a bit complicated to tell another editor which tab size was used by the one used to write the code. 
# Most code in AROS was written this way and your code should look like the rest. 
# You can print this code on any printer without special tools to &quot;fix&quot; the tabs. 
# Most editors have smart tabs which do exactly this. If your editor doesn't, write a bug report.

If you have a function with many arguments (d, e) you should put the parentheses in lines of their own and each argument in one line (d) or put the first argument behind the opening parentheses (e) and each following argument in a line of its own with the comma in front. The closing parentheses is in a line of its own and aligned with the beginning of the expression (i.e. the a and not the opening parentheses or the printf()).

Use a single blank line to separate logical blocks. Large comments should have a blank line before and after them, small comments should be put before the code they explain with only one blank line before them.

If you see any TABS in AROS core sources then the suggestion is to &quot;detab the file and commit that separately&quot; either before or afterwards from making functionality changes. Make two commits instead of one. This makes it easier for others to see the real changes instead of having to dig through multiple lines of irrelevant diffs.

===Eliminating Global Variables===

i.e. pass variables to functions (local scope) or classes making it easier to track and debug your code.

Any time you find that you need a particular thing in 'a lot of different places', chances are that all those places are conceptually related, and so you can create a class, a namespace, a function, or some other higher-level organizational unit to represent that relationship. This makes the program easier to understand.

Bad Designs

* All variables are global. 
* There are no standalone functions, only sub-procedures which act on the global variables. 
* Every sub-procedure is at least 500 lines to several thousand 
* Every sub-procedure has more than one task to perform 
* Copy-paste is preferred to writing methods, AND subtle changes are made in the middle of the code

Good Designs

* structure program into functions (C or basic) - top-down procedural approach 
* put in class(es) (freepascal or C++) - the object is fixed and you use methods to access the object

&lt;pre&gt;
 class String_List
 {
 private:
 list&lt;string&gt; m_List;  // member
 public:
 void read_strings() { /* read strings into m_List */ }
 void print_strings() { /* write contents of m_List to stdout */ }
 void sort_strings() { /* sort contents of m_List */ }
 void sort_strings_reverse() { /* reverse-sort contents of m_List */ }
 void unique_strings() { /* remove duplicate strings */ }
 };

 int main()
 {
 String_List myList;  // local
 myList.read_strings();
 myList.sort_strings();
 myList.print_strings();
 myList.sort_strings_reverse();
 myList.print_strings();
 myList.unique_strings();
 myList.print_strings();
 return 0;
 }
&lt;/pre&gt;

This way it is very easy to replace the list with new list for debugging purposes, or replacing the methods without replacing the list, when you want different results. You only have to replace the content of the local variables.

 So create the structure that matches your data (linked lists, trees, arrays, etc.) and what to do with them (sorting, searching, etc.)

&lt;pre&gt;
.h usually contain #define #include typedef enum struct extern screen and window definitions (data structures)
.c should contains functions and algorithms
&lt;/pre&gt;

One way to look at it is that menu headings act as the .c file and sub-menu headings as functions.

When you start a project, you place a couple of declarations in the include file. As the project continues, you place more and more declarations in the include file, some of which refer to or contain previous declarations. Before you know it, you have a real mess on your hands. The majority of your source files have knowledge of the data structures and directly reference elements from the structures.
Making changes in an environment where many data structures directly refer to other data structures becomes, at best, a headache. Consider what happens when you change a data structure.

Use good variables names to help clarify code and only comment when you need to explain why a certain programming approach was made.

You're Refactoring Legacy Code, you see a global, you want to get rid of it. How do you do this?

Exactly what to do depends on how the global is used. The first step is to find all uses of the global throughout the code, and get a feel for what the significance of the variable is and how it relates to the rest of the program. Pay particular attention to the &quot;lifetime&quot; of the variable (when it gets initialized, when it is first used, when it is last used, how it gets cleaned up). Then, you will probably make the global a data member of a class (for OO languages), or you will write some get/set functions. Converting to the Singleton Pattern is common, but you may discover that it makes more sense for the data element to be a member of an existing singleton, or maybe even an instance variable.

# Create a basic read method, either as a class or a global function. Replace all reads with the access method, but leave the variable defined as a global.
# Review each of the writes to the method and extract action functions one at a time. Unless two operations are coded identically in the original code, extract each write access separately.
# Change the variable scope from global to local.
# Analyze similar action functions to determine if any can be merged, i.e., there are no functional differences in the results of the function, just differences in the implementation details.
# Review the calls to the read method and see if a more complex functionality should be applied. Follow the approach for writes and unless implementations are identical, create separate access functions. 
# Analyze the access functions for duplication.

As returning variables by &quot;passing by value&quot; are forgotten, so &quot;passing by reference&quot; is often used instead. The reference is a pointer to the variable so the value is remembered when returned.

Alternatives

* Hidden Globals
* Singleton Pattern
* Database or TupleSpace
* Context Object 
* Dependency Injection 
* Stateful Procedures


==AROS/AmigaOS APIs and Docs==

&lt;pre&gt;
Library:
   - Private data structure
   - Many public access methods

Device:
   - Private data structure
   - Two (BeginIO/AbortIO) access methods

Resource:
   - Public data structure
   - *NO* access methods
&lt;/pre&gt;

And, being Amiga OS-compatible, there are exceptions to all of these.


===System Libraries===

The [http://developers.aros.org/ AROS Guide To Libraries] can be used as a guide to individual commands and old Dev Docs are used in application programming.

Amiga/Aros styles libraries are very different from windows and linux libs. Typical .so/dll libraries are foreign to most Amiga-like OS 


*[[Aros/Developer/Docs/Libraries/AROSC|arosc.library]]
*[[Aros/Developer/Docs/Libraries/AmigaGuide|amigaguide.library]]
*[[Aros/Developer/Docs/Libraries/ASL|asl.library]]
*[[Aros/Developer/Docs/Libraries/Bullet|bullet.library]]
*[[Aros/Developer/Docs/Libraries/BSDsocket|bsdsocket.library]]
*[[Aros/Developer/Docs/Libraries/CAMD|camd.library]]
*[[Aros/Developer/Docs/Libraries/Codesets|codesets.library]]
*[[Aros/Developer/Docs/Libraries/CGFX|cybergraphics.library]]
*[[Aros/Developer/Docs/Libraries/CGXVIDEO|cgxvideo.library]]
*[[Aros/Developer/Docs/Libraries/Commodities|commodities.library]]
*[[Aros/Developer/Docs/Libraries/DataTypes|datatypes.library]]
*[[Aros/Developer/Docs/Libraries/DiskFont|diskfont.library]]
*[[Aros/Developer/Docs/Libraries/DOS|dos.library]]
*[[Aros/Developer/Docs/Libraries/Exec|exec.library]]
*[[Aros/Developer/Docs/Libraries/Expansion|expansion.library]]
*[[Aros/Developer/Docs/Libraries/FreeType2|freetype.library]]
*[[Aros/Developer/Docs/Libraries/GadTools|gadtools.library]]
*[[Aros/Developer/Docs/Libraries/Graphics|graphics.library]]
*[[Aros/Developer/Docs/Libraries/Icon|icon.library]]
*[[Aros/Developer/Docs/Libraries/Identify|identify.library]]
*[[Aros/Developer/Docs/Libraries/IFFParse|iffparse.library]]
*[[Aros/Developer/Docs/Libraries/Intuition|intuition.library]]
*[[Aros/Developer/Docs/Libraries/Keymap|keymap.library]]
*[[Aros/Developer/Docs/Libraries/Layers|layers.library]]
*[[Aros/Developer/Docs/Libraries/Locale|locale.library]]
*[[Aros/Developer/Docs/Libraries/LowLevel|lowlevel.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingBas|mathieeesingbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubBas|mathieeedoubbas.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEESingTrans|mathieeesingtrans.library]]
*[[Aros/Developer/Docs/Libraries/MathIEEEDoubTrans|mathieeedoubtrans.library]]
*[[Aros/Developer/Docs/Libraries/Mathtrans|mathtrans.library]]
*[[Aros/Developer/Docs/Libraries/MUIMaster|muimaster.library]]
*[[Aros/Developer/Docs/Libraries/Partition|partition.library]]
*[[Aros/Developer/Docs/Libraries/PopUpMenu|popupmenu.library]]
*[[Aros/Developer/Docs/Libraries/OOP|oop.library]]
*[[Aros/Developer/Docs/Libraries/Regina|regina.library]]
*[[Aros/Developer/Docs/Libraries/Reqtools|reqtools.library]]
*[[Aros/Developer/Docs/Libraries/RexxSysLib|rexxsyslib.library]]
*[[Aros/Developer/Docs/Libraries/ScreenNotify|screennotify.library]]
*[[Aros/Developer/Docs/Libraries/TTEngine|ttengine.library]]
*[[Aros/Developer/Docs/Libraries/Thread|thread.library]]
*[[Aros/Developer/Docs/Libraries/Utility|utility.library]]
*[[Aros/Developer/Docs/Libraries/Xadmaster|xadmaster.library]]
*[[Aros/Developer/Docs/Libraries/Workbench|workbench.library]]
*[https://github.com/aros-development-team/AROS/commit/c82e86b8480277998014cc327b56c7664023a52f ClassAct Reaction boopsi class]


===AROS Subsystems===

# [[Aros/Developer/Zune|Zune MUI compatible GUI]]
# [[Aros/Developer/AROSAppPackages|AROS Application Packages]]
# AHI Audio Drivers - [[Aros/Developer/AHIDrivers|Usage]]/[[Aros/Developer/AHIDriversDev|Development]]
# AROSTCP Sana2 Network Interface Drivers - [[Aros/Developer/NICDrivers|Usage]]/[[Aros/Developer/NICDriversDev|Development]]
# [[Aros/Developer/AmiSSL|AmiSSL]]
# gfx.hidd/cybergraphics Video Drivers - [[Aros/Developer/GfxDrivers|Usage]]/[[Aros/Developer/GfxDriversDev|Development]]
# IO Device Drivers - [[Aros/Developer/IODeviceDrivers|Usage]]/[[Aros/Developer/IODeviceDriversDev|Development]]
# USB Device Drivers - [[Aros/Developer/USBDrivers|Usage]]/[[Aros/Developer/USBDriversDev|Development]]
# PCI Device Drivers - [[Aros/Developer/PCIDrivers|Usage]]/[[Aros/Developer/PCIDriversDev|Development]]
# [http://www.libsdl.org/ SDL] [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2013&amp;pid=13333#post_13333 SDL2 coding usage], [https://github.com/search?q=repo%3Aaros-development-team%2Fcontrib%20SDL2&amp;type=code SDL2 commits], [https://github.com/aros-development-team/contrib/commit/c62c3c425c35bac19dadc23be092b0b13a66c76c SDL3 initial commit], []
# [[w:Gallium3D|Gallium 3D]] [http://www.mesa3d.org/ openGL aka Mesa] - [[Aros/Developer/OpenGL|Usage]]/[[Aros/Developer/OpenGLDev|Development]] [http://www.swiftless.com/opengltuts.html Swfitless]
# A small subset of GTK2 through [http://sourceforge.net/projects/gtk-mui/ MUI-GTK] 
# Cairo 2D Engine - [[Aros/Developer/Cairo|Usage]]/[[Aros/Developer/Cairo|Development]]
# [[Aros/Developer/Scalos|Scalos desktop API and plugin modules]]
# [[Aros/Developer/VHI|VHI video driver]]


====HIDDs====

*[[Aros/Developer/Docs/HIDD/HIDDClass|hiddclass.hidd]]
*[[Aros/Developer/Docs/HIDD/Graphics|graphics.hidd]]
*[[Aros/Developer/Docs/HIDD/VesaGfx|vesagfx.hidd]]
*[[Aros/Developer/Docs/HIDD/ATI|radeon.hidd]]
*[[Aros/Developer/Docs/HIDD/NVidia|nvidia.hidd]]
*[[Aros/Developer/Docs/HIDD/Nouveau|nouveau.hidd]]
*[[Aros/Developer/Docs/HIDD/Kbd|kbd.hidd]]
*[[Aros/Developer/Docs/HIDD/Mouse|mouse.hidd]]
*[[Aros/Developer/Docs/HIDD/i2c|i2c.hidd]]
*[[Aros/Developer/Docs/HIDD/IRQ|irq.hidd (deprecated)]]
*[[Aros/Developer/Docs/HIDD/PCI|pci.hidd]]
*[[Aros/Developer/Docs/HIDD/PCIPC|pcipc.hidd]]
*[[Aros/Developer/Docs/HIDD/Serial|serial.hidd]]
*[[Aros/Developer/Docs/HIDD/Thunderbolt|thunderbolt.hidd]]
https://github.com/aros-development-team/AROS/commit/4f02ea691799aff3a01f60cfa5f9182c82fc57a8

HIDD are used for device/peripheral low level hardware support drivers. The HIDD system is split up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.
      
In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

HIDD API is heavyweight though. You need to open a HIDD library, open oop.library, instantiate an object (even if there's no object); and object calls are more costly compared to plain library calls.


Basically your task is to implement a subclass of hidd.ata.bus for your hardware. just implementing the XXXATA__Hidd_ATABus__xxxxxx methods for the Amiga chipset - and appropriate versions of the interface_xxx.c file(s). pretty much everything in probe.c could be ignored - just write a replacement scan for relevant amiga devices and store whatever info you need in the bus data? only the &quot;SUPPORT_LEGACY&quot; blocks might be related.

You do not need to depend on PCI API. PCI is just a way to discover the hardware on PCs, etc. 
&lt;hidd/pci.h&gt; includes (at some depth) &lt;interface/HW.h&gt;, which defines IID_HW. This comes from the 'generic' HIDD class in: 
 rom/hidds/hidd/hiddclass.conf
did not split up HIDD and HW because they are always used in pair. It's the same as hidd/pci.h bringing definition for: PCI, PCIDriver and PCIDevice. PCI is actually PCIHW, just the name was not changed for backwards compatibility reasons. HW is a 'hub' where HIDD instances plug in.

ATA HIDD aoHidd_ATABus_Use32Bit value is completely ignored unless ata.device first detects correct command line parameter.
Yes. Unfortunately I was unable to find any comment in code or svn history with explanations. Looked  at Linux source, there 32-bit PIO is also controller driver's property. Some of them enable it, some don't.

Actually, switching the default to ON should be safe. ata.device is fail-safe at this because during IDENTIFY command it validates upper 16  bits,  and  if they appear to be zeroes in all 128 longwords, then 32-bit mode is switched off. But, nevertheless, I know how tricky hardware can be, so I decided not to change original behavior. If  you think it's wrong in some cases, then it's possible to add one more  attribute  like  aHidd_ATABus_Default32Bit. If set to YES, then  this means that 32-bit PIO is safe to use by default.


====Devices====

*[[Aros/Developer/Docs/Devices/ATA|ata.device]]
*[[Aros/Developer/Docs/Devices/Console|console.device]]
*[[Aros/Developer/Docs/Devices/Narrator|narrator.device]]
*[[Aros/Developer/Docs/Devices/Printer|printer.device]]
*[[Aros/Developer/Docs/Devices/Trackdisk|trackdisk.device]]
*[[Aros/Developer/Docs/Devices/AmberRAM|amberram.device]]
*[[Aros/Developer/Docs/Devices/Timer|timer.device]]
*[[Aros/Developer/Docs/Devices/|.device]]

The Amiga used [[Aros/Developer/Docs/Devices|Devices]] to communicate with [http://aros-exec.org/modules/newbb/viewtopic.php?start=0&amp;topic_id=3475&amp;viewmode=flat&amp;order=ASC additional hardware]. AROS has replaced these hardware devices with hidd equivalents but some are still retained for backwards compatibility.

Local libraries/devices/handlers,etc. are supposed to override the ones in ROM if their version is higher than the one in ROM.

Here is the list of commands exec default: 
{| class=&quot;wikitable&quot;
| CMD_CLEAR
|  Purge the buffer of the device
|----
| CMD_READ
|  Playback Control
|----
| CMD_STOP
|  Stopped the activity of the device
|----
| CMD_FLUSH
|  Empty the queue of commands
|----
| CMD_RESET
|  Reset a device
|----
| CMD_WRITE
|  Playback Control
|----
| CMD_INVALID
|  Create an error
|----
| CMD_UPDATE
|  Gets updated device
|----
| CMD_START
|  Will restart the device
|----
|}

While most other &quot;stuff you communicate with&quot; in AmigaOS are devices &lt;ref&gt;AMIGA ROM Kernel Reference Manual: Devices, 3rd Edition. Commodore-Amiga, Inc. Addison-Wesley, 1991. {{ISBN|0-201-56775-X}}&lt;/ref&gt; that share a [http://gega.homelinux.net/AmigaDevDocs/ common base interface]. [[Aros/Developer/Docs/Devices1.3|OS 1.3 Device Drivers]].


====Handlers====

:[[Aros/Developer/Docs/Handlers/Pipe|pipe.handler]]
:[[Aros/Developer/Docs/Handlers/Port|port.handler]]
:[[Aros/Developer/Docs/Handlers/SFS|sfs.handler]]
:[[Aros/Developer/Docs/Handlers/FAT|fat.handler]]
:[[Aros/Developer/Docs/Handlers/PFS|pfs.handler]]
:[[Aros/Developer/Docs/Handlers/NTFS|fuse.handler]]
:[[Aros/Developer/Docs/Handlers/FFS|ffs.handler]]

filesystem handlers have their own separate system consisting of completely differently structured messages that dos.library use to pass requests (for things like reading, writing, getting directory contents etc.) to them. AROS originally went with implementing filesystem handlers as devices, which might arguably be more consistent with the rest of the AmigaOS API but which is quite incompatible with AmigaOS itself. However, it made it far harder to port filesystems and the gains were comparatively small, and so there's been a long standing goal of fixing this incompatibility. It has now, June 2011, been reintroduced to all AROS flavors.

are argstr and argsize valid for the handler startup environment?
DOS/RunHandler() calls DOS/CreateNewProcTags(), and then CallEntry() (in rom/dos/exit.c) to start the handler, so yes, argstr and argsize are *present* in the call signature of the handler.

Granted, argstr will be NULL and argsize 0, but those values *are* passed to the handler function using:

&lt;pre&gt;
AROS_UFC3(ULONG, entry,
                         AROS_UFCA(STRPTR, argptr, A0),
                         AROS_UFCA(ULONG, argsize, D0),
                         AROS_UFCA(struct ExecBase *, SysBase, A6));
&lt;/pre&gt;

Creating your own [without the whole build tree http://pagesperso-orange.fr/franck.charlet/temp/radeon.zip] and then  
&lt;pre&gt;
make stub
make
make install
&lt;/pre&gt;

SFS has two Root blocks, one at the start and one at the end of the disk. The Root blocks both contain the same information.  They hold various information about the disk structure and have the locations of some important blocks used by the filesystem.  

The Root ObjectContainer contains the Root directory Object. The name of this Object is the name of the volume. It is identical to a normal directory Object.

The Bitmap is used to keep track of free space. Each bit in a bitmap represents a single block. A set bit indicates a free block and a cleared bit a used block.

AdminSpaceContainers are used to keep track of space which has been reserved for storing administration blocks. Only the Bitmap, the Root blocks and the actual data stored in files aren't stored in administration space. Administration space is allocated in chunks of 32 blocks at a time. A single AdminSpaceContainer can hold information about a large number of such areas each of which has its own little bitmap of 32 bits.

Extents are stored in a B-Tree. The Root block holds a pointer to the root of the Extent B-Tree. Extents keep track of space in use by a specific file. Each fragment a file consists of has its own Extent. Extents are in a double linked list. The list can be used to locate the next or previous fragment of a file.

Below is the standard block header. This header is found before EVERY type of block used in the filesystem, except data blocks.  The id field is used to check if the block is of the correct type when it is being referred to using a BLCK pointer.  The checksum field is the SUM of all LONGs in a block plus one, and then negated. When applying a checksum the checksum field itself should be set to zero. The checking a checksum the checksum is okay if the result of the checksum equals zero. The ownblock BLCK pointer points to the block itself. This field is an extra safety check to ensure we are using a valid block.

Field	Type	Description
id	ULONG	The id field is used to identify the type of block we are dealing with. It is used to make sure that when referencing a block we got a block of the correct type. The id consist of 4 bytes and each blocktype has its own unique foure letter code.
checksum	ULONG	This field contains the sum of all longs in this block, plus one and then negated. The checksum can be used to check if the block hasn't been corrupted in any way.
ownblock	BLCK	Points to itself, or in other words, this field contains the block number of this block. This is yet another way to check whether or not a block is valid.

&lt;pre&gt;
struct fsBlockHeader {
    ULONG id;
    ULONG checksum;
    BLCK ownblock;
};
&lt;/pre&gt;
The algorithm to calculate the checksum of a block:
&lt;pre&gt;
ULONG calcchecksum(struct fsBlockHeader *block, LONG blocksize} {
    ULONG *data=(ULONG *)block;
    ULONG checksum=1;

    block-&gt;checksum=0;

    while(blocksize&gt;0) {
        checksum+=*data++;
        blocksize-=4;
    }

    return(-checksum);
} 
&lt;/pre&gt;

A Root block contains very important information about the structure of a SFS disk. It has information on the location and size of the disk, the blocksize used, locations of various important blocks, version information and some filesystem specific settings.

A SFS disk has two Root blocks; one located at the start of the partition and one at the end. On startup the filesystem will check both Roots to see if it is a valid SFS disk. If either one is missing SFS can still continue (although at the moment it won't).

A Root block could be missing on purpose. For example, if you extend the partition at the end (adding a few MB's) then SFS can detect this with the information stored in the Root block located at the beginning (since only the end-offset has changed).   Same goes for the other way around, as long as you don't change start and end point at the same time.

When a Root block is missing because the partition has been made a bit larger, then SFS will in the future be able to resize itself without re-formatting the disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
version	UWORD	The version of the filesystem block structure. You can check this field to identify what version of the filesystem your dealing with it and to see if you can handle this structure correctly. Don't try to interpret the disk's structure when this field contains an unknown version number!

sequencenumber	UWORD	Used to identify which Root block was written last in case the sequencenumber on both Root blocks don't match.
datecreated	ULONG	Creation date of this volume. This is the date when the disk was last formatted and will never be changed.

bits	UBYTE	Various settings, see below.
&lt;pre&gt;
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
reserved1	ULONG[2]	Reserved, leave zero.
firstbyteh	ULONG	High 32-bits of a 64-bit number. This is the first byte of our partition relative to the start of the disk.
firstbyte	ULONG	Low 32-bits of a 64-bit number.
lastbyteh	ULONG	High 32-bits of a 64-bit number. This is the last byte (exclusive) of our partition relative to the start of the disk.
lastbyte	ULONG	Low 32-bits of a 64-bit number.
totalblocks	ULONG	The total number of blocks this partition consists of.
blocksize	ULONG	The size of a block of this partition.
reserved2	ULONG[2]	Reserved, leave zero.
reserved3	ULONG[8]	Reserved, leave zero.
bitmapbase	BLCK	Block number of the start of the Bitmap.
adminspacecontainer	BLCK	Block number of the first AdminSpaceContainer.
rootobjectcontainer	BLCK	Block number of the ObjectContainer which contains the root of the disk (this is where the volume name is stored).
extentbnoderoot	BLCK	Block number of the root of the Extent B-Tree.
reserved4	ULONG[4]	Reserved, leave zero.
&lt;/pre&gt;

&lt;pre&gt;
struct fsRootBlock {
  struct fsBlockHeader bheader;
  UWORD version;
  UWORD sequencenumber;
  ULONG datecreated;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  ULONG reserved1[2];
  ULONG firstbyteh;
  ULONG firstbyte;
  ULONG lastbyteh;
  ULONG lastbyte;
  BLCK  totalblocks;
  ULONG blocksize;
  ULONG reserved2[2];
  ULONG reserved3[8];
  BLCK  bitmapbase;
  BLCK  adminspacecontainer;
  BLCK  rootobjectcontainer;
  BLCK  extentbnoderoot;
  ULONG reserved4[4];
};
&lt;/pre&gt;

AdminSpaceContainers are used to store the location and bitmap of each administration space. The AdminSpaceContainers are located in a double linked list and they contain an array of fsAdminSpace structures.  There is one fsAdminSpace structure for every administration space on disk.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
next	BLCK	The next AdminSpaceContainer, or zero if it is the last in the chain.
previous	BLCK	The previous AdminSpaceContainer, or zero if it is the first AdminSpaceContainer.
bits	UBYTE	The number of bits in each in the bits ULONG in the fsAdminSpace structure.
pad1	UBYTE	Reserved, leave zero.
pad2	UWORD	Reserved, leave zero.
adminspace	struct fsAdminSpace	An array of fsAdminSpace structures. The size of the array is determined by the current blocksize.
&lt;pre&gt;
struct fsAdminSpaceContainer {
  struct fsBlockHeader bheader;
  BLCK next;
  BLCK previous;
  UBYTE bits;
  UBYTE pad1;
  UWORD pad2;
  struct fsAdminSpace adminspace[0];
};
&lt;/pre&gt;
Field	Type	Description
space	BLCK	The first block of an administration space.
bits	ULONG	A small bitmap which is used to determine which blocks in an administration space are already in use. The number of bits in this bitmap is determined by the bits field in the AdminSpaceContainer.
&lt;pre&gt;
struct fsAdminSpace {
  BLCK  space;
  ULONG bits;
};
&lt;/pre&gt;

The fsBitmap structure is used for Bitmap blocks. A bitmap block is used to keep track of which space is in use and which isn't for a particular area of a disk.  All bitmap blocks together keep track of the free space for an entire disk. The location of the first bitmap block is known and all other bitmap blocks are stored in order after the first one.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
bitmap	ULONG	An array of ULONG's.  These hold the actual information on which blocks are in use and which aren't.
&lt;pre&gt;
struct fsBitmap {
    struct fsBlockHeader bheader;
    ULONG bitmap[0];
};
&lt;/pre&gt;
Each bit in a bitmap block (except for the block header) represents a single block. If the bit is set than the block is free, and if the bit is clear then it is full. The first ULONG in the bitmap area of the first bitmap block represents blocks 0 through 31 on the disk. Bit 31 of this ULONG is block 0, 30 is block 1, and so on. Bit 0 of the first ULONG represents block 31.

Below is a table to clarify how bitmaps work even further. The first column is the bitmap block number, the second column is the number of the ULONG in the bitmap array. The third column is the bit number in this ULONG, and the last column is the block which this specific bit, in this specific bitmap block represents.

We'll assume here that a bitmap block has room for 120 ULONG's (meaning there is room for storing 32 * 120 bits).

&lt;pre&gt;
Bitmap block	ULONG number	Bit number	Block represented
1 (first)	0	31	0
1	0	30	1
...	...	...	...
1	0	1	30
1	0	0	31
1	1	31	32
...	...	...	...
1	2	31	64
1	2	30	65
...	...	...	...
1	119	0	3839
2	0	31	3840
2	0	30	3841
...	...	...	...
&lt;/pre&gt;
The last bitmap block doesn't need to be completely used. The unused bits (which belong to blocks which do not exist) all have to be clear, to indicate that these blocks are in use.

The fsObjectContainer structure is used to hold a variable number of fsObjects structures (Objects) which have the same parent directory. Each ObjectContainer must contain at least one Object. If there is space in the ObjectContainer not used by the variable number of Objects then that space is zero filled. Objects always start at 2-byte boundaries, which means sometimes a padding byte is inserted between two Objects.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the parent Object, or 0 if this object has no parent (which is only the case for the Root directory).
next	BLCK	The next ObjectContainer belonging to this directory, or zero if it is the last in the chain.
previous	BLCK	The previous ObjectContainer belonging to this directory, or zero if it is the first ObjectContainer in this directory.
object	struct fsObject	A variable number of fsObject structures. The number of structures depends on the individual sizes of each fsObject structure and the blocksize. These structures are located directly after each other with at most 1 byte of padding between them to get the structures aligned on a 2 byte boundary.
&lt;pre&gt;
struct fsObjectContainer {
    struct fsBlockHeader bheader;
    NODE parent;
    BLCK next;
    BLCK previous;
    struct fsObject object[0];
}; 
&lt;/pre&gt;

fsHashTable is the structure of a HashTable block. It functions much like the hash table found in FFS user directory blocks, except that it is stored in a separate block. This block contains a number of hash-chains (about 120 for a 512 byte block). Each hash-chain is a chain of Nodes. Each Node has a pointer to an Object and a pointer to the next entry in the hash-chain.  Using such a hash-chain you can locate an object quickly by only knowing its name.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
parent	NODE	The node number of the directory Object this HashTable block belongs to.
hashentry	NODE	An array of Nodes. Each Node represents the start of a hash-chain (singly linked). A hash-value is calculated using the name of a file or directory, and this value determines in which chain the Object is linked. If there are no entries in a hash-chain then the hashentry value is zero.
&lt;pre&gt;
struct fsHashTable {
    struct fsBlockHeader bheader;
    NODE parent;
    NODE hashentry[0];
};
&lt;/pre&gt;
To calculate the hash-value using a name of an Object as input use these routines:
&lt;pre&gt;
UWORD calchash(UBYTE *name) {
    UWORD hash=0;
    /* Calculates a hash value over the passed in string.
       The end of the string can be either a NUL byte or a
       slash. The hash function is the same as the one
       used in FastFileSystem set to international mode. */
    while(name[hash]!=0 &amp;&amp; name[hash]!='/') {
        hash++;
    }
    while(*name!=0 &amp;&amp; *name!='/') {
        hash=hash*13+upperchar(*name++);
    }

    return((UWORD)(hash % (UWORD)((blocksize-sizeof(struct fsHashTable))&gt;&gt;2)));
}
UBYTE upperchar(UBYTE c) {
    if((c&gt;=224 &amp;&amp; c&lt;=254 &amp;&amp; c!=247) || (c&gt;='a' &amp;&amp; c&lt;='z')) {
        c-=32;
    }
    return(c);
}
&lt;/pre&gt;

The BNodeContainer is used to store B-Trees. Currently only one B-Tree is in use by this filesystem and it is used to store the location of file data. The fsBNodeContainer structure contains two other structures. The fsBlockHeader structure and the BTreeContainer structure.

Field	Type	Description
bheader	struct fsBlockHeader	Standard block header.
btc	struct BTreeContainer	Contains information about the B-Tree and its nodes contained in this block.
&lt;pre&gt;
struct fsBNodeContainer {
    struct fsBlockHeader bheader;
    struct BTreeContainer btc;
}; 
&lt;/pre&gt;


First try and locate the Root block. It should start with &quot;ROOT&quot;.  SFS has two of these, one at the start of the partition and one at the end.  One of the fields contains the block size, which will be the size of all important SFS blocks.

The root block has the root object container, which contains information about files and directories in the root directory.  The object 
containers basically hold one or more smaller structures that represent files and directories.  Scanning them all should give you a list of 
files and directories.

The root block also has the root of the Extent B-Tree.  This is a standard B-Tree structure (not a binary tree) that is used commonly in 
all kinds of system, you can read about how they work on Wikipedia if needed.  The B-Tree holds the information about *where* all the data is 
located for your files.

To recover your files, I'd do this:

* Find one of the root blocks, if not present, then figure out the block size your disk was using, and scan every block in turn to see if it 
looks like an ObjectContainer (check the fsBlockHeader's ID, check if the ownblock number is equal to the block you are currently scanning, 
and check its checksum).  So if you currently have block 12, and you see a block with the correct id, and ownblock = 12 and its checksum is good, 
then that's probably a valid ObjectContainer.

* With all the ObjectContainers found, you can extract filenames and directory names from these, but also the number of their first data 
block (in the field data) and the file size.  For small files (less than blocksize) this data block will be enough to recover the data.
For larger files, you might be lucky and all the remaining blocks are found after the first one (if the file was defragmented).  You can't be
sure of that though so...

* For larger files, you need to find all the BNodeContainers.  You could scan these in the same way you found all the ObjectContainers (look for 
blocks with the correct id, ownblock number and checksum). 

* With all the BNodeContainers found, you can try looking up the first data block of a file in the B-Tree structure.  This is a bit complicated 
-- the B-Tree consists of non-leaf nodes (blocks that only contain pointers to other B-Tree blocks), the isLeaf flag indicates this.  Or it 
can be a B-Tree leaf block.  The leaf blocks contain extra information per entry (see https://hjohn.home.xs4all.nl/SFS/extents.htm)
&lt;pre&gt;
struct fsExtentBNode {
     ULONG key;
     ULONG next;
     ULONG prev;
     UWORD blocks;
};
&lt;/pre&gt;

The key should be a block of a file (the first of a range), that is 1 to 65535 block long (depending the &quot;blocks&quot; field).  If the file is split 
up into more parts, then &quot;next&quot; will contain block number of the next range of blocks.  You need to look this up again in the B-Tree 
structure to find out how large it is. 

You can for the most part ignore the other structures (bitmap, admin containers).  The fsObjects and B-tree containers is what you'll need to 
recover the data. 


====Resources====

&lt;pre&gt;
rom/storage/mmakefile.src 
rom/storage/storage.conf 
rom/storage/storage_device.c 
rom/storage/storage_ids.c 
rom/storage/storage_init.c 
rom/storage/storage_intern.h 
rom/storage/storage_mount.c 
rom/storage/storage_unit.c
&lt;/pre&gt;

&lt;pre&gt;
rom/storage/includes/device.h 
rom/storage/includes/unit.h 
rom/storage/includes/volume.h 
rom/storage/storage_intern.h 
&lt;/pre&gt;

&lt;pre&gt;

&lt;/pre&gt;

*[[Aros/Developer/Docs/Resources/ACPI|acpi.resource]]
*[[Aros/Developer/Docs/Resources/Battclock|battclock.resource]]
*[[Aros/Developer/Docs/Resources/Bootloader|bootloader.resource]]
*[[Aros/Developer/Docs/Resources/Cia|cia.resource]]
*[[Aros/Developer/Docs/Resources/Filesystem|FileSystem.resource]]
*[[Aros/Developer/Docs/Resources/Hostlib|hostlib.resource]]
*[[Aros/Developer/Docs/Resources/Kernel|kernel.resource]]
*[[Aros/Developer/Docs/Resources/Misc|misc.resource]]
*[[Aros/Developer/Docs/Resources/Processor|processor.resource]]


==Debugging Code==

Please use the [http://sourceforge.net/tracker/?group_id=43586&amp;atid=439463 AROS Bug Tracker] if any issues are found.


GRUB Command line list

&lt;pre&gt;
sysdebug  
usbdebug - allows to see Poseidon's log in debug output
&lt;/pre&gt;


How do I get debugging out of InitResident ? If running i386 hosted on linux sysdebug=initresident on command line.
This  way  you can enable any of listed flags. sysdebug=all stands for &quot;everything&quot;


Have an executable (crosscompiled C++ code) which has 6 MB size on disk, but after loading it in memory, 250 MB RAM is taken. Any software that would split AROS executable into ELF part which would show actual size values?

 readelf -S executable

it will show you all sections in elf file, including sizes and requested alignment.

 objdump -h filename

That's will give you a quick overview of the sections and sizes. Ignore all the .debug.* sections. 
Would hazard a guess that you have a large .bss section. That's pretty common in C++.

Next step:

 nm—size-sort filename | grep ' [bB] '

The last few will be your biggest consumers. Would suggest -C to demangle the symbols... ;)


Suggest profiling the program (just use some printf's in the main loop for time spent in each part), it usually is quite easy to spot slow parts in games or apps.

If someone has '#define IPTR ULONG' somewhere. To see where that define is, redefine IPTR in the source code that fails, just above the line that fails, and the preprocessor will tell you where it was defined first.

===How to setup gdb with AROS/hosted===

Download AROS sources (AROS-xxxxxxxx-source.tar.bz2, where xxxxxxxx is the current date) and AROS contrib sources (AROS-xxxxxxxx-contrib-source) from 

Untar-bzip2 and cd to the unpacked archive directory.

 &gt; tar -xvjf AROS-xxxxxxxx-source.tar.bz2
 &gt; cd AROS-xxxxxxxx-source

Check the link to &quot;contrib&quot; (contrib-source) inside directory, e.g. correct like this:

 &gt; rm contrib
 &gt; ln -s ../AROS-xxxxxxxx-contrib-source.tar.bz2 contrib

Make sure you have the correct locale setting, otherwise compilation will fail at some point. See [http://aros.sourceforge.net/documentation/developers/compiling.php#setting-the-locale-to-iso8859 here] (or link below) for more on that. You might have to enter this:

 &gt; export LANG=&quot;en_US.ISO-8859-1&quot;

Now configure for a debug build - see &quot;./configure --help&quot; for more - here are two examples:

 &gt; ./configure—enable-debug=stack,modules,symbols
 
 &gt; ./configure—enable-debug=all

You may &quot;make&quot; now, or choose a separate directory for your build (e.g. for easy removal), for example if compiling for i386 architecture you could create a directory like this:

 &gt; mkdir linux-i386
 &gt; cd linux-i386
 &gt; ../AROS/configure—enable-debug=stack,symbols,modules

When done configuring you're ready to go:

 &gt; make

Building AROS takes some time - minutes on fast machines (e.g. 2.5&amp;nbsp;GHz quadcore), up to hours on slower machines.
The result will be AROS Linux hosted with gdb debugging enabled.

See aros.org documentation for more on compiling AROS, including more [http://aros.sourceforge.net/documentation/developers/compiling.php --enable-debug] options.


When finished, enter bin/linux-i386/AROS directory (replace &quot;linux-i386&quot; with your compilation target platform, e.g. linux-x86_64, etc.) inside the unpacked archive directory. This directory contains the required .gdbinit file for properly running AROS inside gdb.

 &gt; cd bin/linux-i386/AROS

Run AROS (here: with 128MB of memory) from gdb:

 &gt; gdb—args boot/aros-unix -m 128
or
 &gt; gdb—args boot/arosboot -m 128

 (gdb) r

Watch the shell output - in case AROS complains about &quot;LoadKeyCode2RawKeyTable: Loading &quot;DEVS:Keymaps/X11/keycode2rawkey.table&quot; failed!&quot; you should also see some instructions on how to create a keymap table. (see link above &quot;more on compiling&quot;, too.)
Quit gdb, and try default keymap table:

 (gdb) q
 The program is running.  Quit anyway (and kill it)? (y or n) y
 &gt; cd ../../..
 &gt; make default-x11keymaptable

Re-run AROS, as described above. Try e.g. RAros (= right windows key) + W to open a shell. If this doesn't work you have to create a keymap table yourself, quit gdb again, and make a new keytable:

 &gt; make change-x11keymaptable

A window will open. Watch the window's title bar, and follow the instructions.

When done, re-run AROS. RAros + W should now open a shell.

Next, compile your program with gdb support.


When you start GDB is there a warning which says

   warning: File &quot;&lt;whatever&gt;/.gdbinit&quot; auto-loading has been declined by your `auto-load safe-path' set to ...

If so start gdb with &quot;-ix .gdbinit&quot;


&lt;pre&gt;
Summary - In short:

* build AROS with debugging support (i.e. ./configure --enable-debug=all)
* build your application with debugging support (i.e. option -g)
* run AROS in the GNU debugger (you may use the GUI frontend &quot;ddd&quot; which simplifies usage a bit)
* start your application
* use the commands &quot;findaddr&quot; and &quot;add-symbol-file&quot; as written in the debugging manual
* if the debugger doesn't find the source code of your application use the &quot;dir&quot; command of the debugger. 
&lt;/pre&gt;

===How to use gdb===

In AROS open a shell, then (in host shell) use CTRL-Z to go into gdb. Use &quot;b Exec_CreatePool&quot; (one of the functions used early on by startup code in programs) to add a breakpoint, then &quot;cont&quot; and gdb will interrupt somewhere early during startup of &quot;program&quot;. Use &quot;bt&quot; to show backtrace and &quot;loadseg&quot; for &quot;??&quot; entries. One of them will be for &quot;program&quot;. After that you can use &quot;disassemble program&quot;.

One thing you need to make sure is that .gdbinit you have in your build directory is the same as in source tree. It has been modified some time ago, but the build system does not refresh it - you need to copy it manually

To recap, please read our debugging [http://aros.sourceforge.net/documentation/developers/debugging.php manual]:


To detect segfaulting when loading, try...

 ./configure—enable-debug—with-optimization=&quot;-O2&quot;

Because crash or no crash may depend on optimization. For newer compilers maybe this helps...

 --with-optimization=-&quot;-O2 -fno-strict-aliasing&quot;

One way to make crashes less random (more easily reproducible) is to activate the munging of free memory in rom/exec/freemem.c which is normally commented out:

&lt;pre&gt;
Index: freemem.c
===================================================================
--- freemem.c   (revision 34289)
+++ freemem.c   (working copy)
@@ -154,11 +154,12 @@
         * created with their TCB placed in the tc_MemEntry list. The workaround
         * is to avoid munging when FreeMem() is called with task switching disabled.
         */
+
        /* DOH! it doesn't work even this way. What's wrong???
-        *
-        * if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
-        *      MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);
         */
+
+       if ((SysBase-&gt;TDNestCnt &lt; 0) &amp;&amp; (SysBase-&gt;IDNestCnt &lt; 0))
+           MUNGE_BLOCK(memoryBlock, MEMFILL_FREE, byteSize);

     }
&lt;/pre&gt;

Mungwall can be turned on at runtime. Currently this works in all hosted versions. Just specify &quot;mungwall&quot; on kernel command line and it works. It can work on native too. In order to enable it you need to parse kernel command line, and if &quot;mungwall&quot; is present, set EXECF_MungWall bit in IntExecBase.IntFlags.

This needs to be done before the first AllocMem() for obvious reasons. And never reset back this flag! If you change it on a working system, you are doomed.

Hosted ports do the processing in rom/exec/prepareexecbase.c --enable-debug=mungwall option in configure still works but is going obsolete.  A kludge in rom/exec/allocmem.c is responsible for this and it needs to be removed when the transition is done.

BTW,  on  i386-pc  port it can be activated by &quot;mungwall&quot; argument on command line, you don't need to rebuild AROS.
New mungwall affects not only AllocMem()/FreeMem(), but also pools. I also tested it with AllocAbs(), seems to work correctly.

Runtime mungwall works on:

* pc-i386
* pc-x86_64
* linux-i386
* linux-x86_64
* darwin-x86
* linux-ppc

Works on all hosted ports, if the port itself is working.

* amiga-m68k
* Not on sam440-ppc and efika-chrp-ppc, even if they would be able to be built at moment. Does not work on (for now, need NVRAM support)

When starting my freshly rebuilt i386-linux-aros which was compiled with full debugging support I get sometimes the error &quot;Program exited with code 0377&quot;. Add the following to your .gdbinit: 
 set follow-fork-mode child

Here are some of the custom AROS gdb functions (defined in &quot;.gdbinit&quot; file) to resolve &quot;in ?? ()&quot; entries in backtrace: 
&lt;pre&gt;
#0 0xb7ffd424 in __kernel_vsyscall ()
#1 0xb7e2a657 in sigsuspend () from /lib/libc.so.6
#2 0xb7c63900 in ?? ()
#3 0xb7c640e3 in ?? ()
#4 0xb7c641e0 in ?? ()
&lt;/pre&gt;

You can use

 loadseg 0xb7c63900
 loadframe 2
or
 loadbt
and some others. Use &quot;help &quot; for a little help text. If the commands do not work try &quot;loadkick&quot; first.


Use &quot;thistask&quot;, &quot;taskready&quot;, &quot;taskwait&quot; to get list of AROS tasks. &quot;bttask &quot; shows backtrace of a task which is in ready or in wait queue and &quot;loadseg&quot; to resolve &quot;??&quot; entries in it's backtrace (&quot;loadframe&quot; would not work as it assume current running task).

===Native debugging tools for AROS===

 to enable debugging at boot time entering the GRUB menu editing line (E key) and adding &quot;debug=memory&quot; to your boot line, then press Ctrl+X to complete booting.


SYS:Tools/Debug/'''Bifteck'''

Open a shell and enter the line below to run Biftek and grab the debug messages collected in RAM into a text file.

 tools/debug/bifteck &gt; ram:debug.txt

and certainly does not open a window. It is a shell tool and only dumps data located from the debug location.
It is therefore important to 'catch' that debug data as soon as possible (before it gets overridden). You should invoke bifteck at the first opportunity before doing anything else.  You can use the TO option to store bifteck output to a file or you can pipe it manually to a file.  


SYS:Tools/Debug/'''Sashimi''' - displays error messages

One suggestion is to do a bug() debugging. Each time bug() is executed it will be output on sashimi. 
You include &lt;aros/debug.h&gt; and place bug(&quot;something\n&quot;); in your source code at location though which control passes.

To get the output - open an aros shell

 SYS:Tools/Debug/sashimi &gt; RAM:out.txt

'''Ctrl C''' to end the output to the RAM Disk.

# open shell, and type
# ram: (to switch to ram drive)
# System:Tools/Debug/Sashimi &gt; mylogfile.txt
# open AHI prefs using wanderer (or use another opened shell)
# play test sound
# close AHI prefs
# shell still open with Sashimi running: press ctrl-c to break Sashimi and return to prompt.
# in shell: copy mylogfile.txt System: (or to your required location)


SYS:Utilities/'''Snoopy''' - monitors OS function calls, run &quot;Sashimi&quot; to see Snoopy's output


SYS:Tools/'''WiMP'''    - the Window (and Screens) Manipulation Program

You can use the -E option of gcc to find out how preprocessor macros are expanded.

===Errors===

crash in strcasecmp usually means that one of its arguments is NULL.

empty space between these two names, prossibly some invisible character 

Old Amiga [http://www.amigacoding.com/index.php?title=Guru_codes&amp;redirect=no Guru Codes]

If the crash is in intuition. Sometimes, if it relates to text, a null pointer sets it off. 
an uninitialised pointer can have any address (this is a common fault).


Compiling on 64bit, Many old code would not properly typecast when doing pointer-integer conversions and thus at least throw a warning. This can easily be located and fixed.

[http://www.aros.org/cs/documentation/developers/app-dev/portable.php Portable code] 

* Use texteditor or some tool to replace all &quot;ULONG&quot; with &quot;IPTR&quot; and &quot;LONG&quot; with &quot;SIPTR&quot; in the sources.
* Fix (change IPTR/SIPTR back to ULONG/LONG) the few places which really rely on ULONG/LONG being exactly 32 bit. That's for things like pixel (ARGB) buffers, structs written/read to disk, colormaps, but probably not much else.

Then again, many current compilers also throw a warning when you try to assign a pointer value to an integer and the integer is possibly too small. This happens under .NET for example when a 64 bit pointer is assigned to something like an ULONG - so exactly the case which you described.


=== Example ===

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/* 1. Header for your name,date,purpose of program.
2. Pre-processor directives. This will include the #includes for files you want to add. 
3. Includes for function prototypes if necessary.
4. Main()
Create Pointers for Libraries and any Window you want to open.
5. Open necessary libraries.
6. Check if open exit program if fail.
7. Open a window exit program if fail.
8. Add your program
9. Close Window
10 Close Libraries.
11 End Program. */

/* standard os included headers &lt;.h&gt; */
#include &lt;dos/dos.h&gt;
#include &lt;dos/dosasl.h&gt;
#include &lt;dos/dosextens.h&gt;
#include &lt;dos/exall.h&gt;
#include &lt;dos/rdargs.h&gt;
#include &lt;exec/memory.h&gt;
#include &lt;exec/types.h&gt;
#include &lt;utility/utility.h&gt;
#include &lt;intuition/intuition.h&gt;

/* define as unresolved external references (proto/xxx.h) and compiler will link to auto(matically) open library */ 
#include &lt;proto/arossupport.h&gt;
#include &lt;proto/dos.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;proto/intuition.h&gt;
#include &lt;proto/graphics.h&gt;
#include &lt;proto/cybergraphics.h&gt;
#include &lt;proto/datatypes.h&gt;
#include &lt;proto/icon.h&gt;

#include &lt;workbench/workbench.h&gt;
#include &lt;workbench/icon.h&gt;

#include &lt;datatypes/pictureclass.h&gt;

#include &lt;proto/muimaster.h&gt;
#include &lt;libraries/mui.h&gt;

#include proto/bsdsocket.h

#include &lt;ctype.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

/* my own headers &quot;.h&quot; */

#define CTRL_C      (SetSignal(0L,0L) &amp; SIGBREAKF_CTRL_C)
#define  isDir(fib) ((fib)-&gt;fib_DirEntryType &gt;= 0)

#define ARG_TEMPLATE    &quot;FILE/A,ALL/S,QUIET/S,W=WIDTH/N,H=HEIGHT/N,M=METHOD,DEFTOOL&quot;

int main(void)
{


	return retval;
} /* main */
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

If you used c++, there is not yet c++ support in our shared library system. 
The easiest way to create / compile a shared library would be to use the AROS build system but the libraries can be created manually. You have to create a ROMTAG structure and some header files.  

A shared library is built with the %build_module macro with a line like this:

 %build_module mmake=MetaTarget modname=mylib modtype=library files=SourceFiles 

This macro can build different AROS module types, like devices, Zune classes, HIDDs, etc.

&lt;pre&gt;
##begin config
version 1.0
##end config

##begin functionlist
void func1(LONG a, LONG b)
int func2(char *s, ULONG a)
##end functionlist
&lt;/pre&gt;


Alternatively,  

&lt;pre&gt;
#ifndef LIB_H
#define LIB_H

#define __NOLIBBASE__

#include &lt;exec/libraries.h&gt;
#include &lt;exec/semaphores.h&gt;
#include &lt;dos/dos.h&gt;

#ifdef __AROS__
//#include &lt;aros/debug.h&gt;
#define reg(x)
#define __saveds
#endif

#define USESYSBASE struct ExecBase *SysBase = Base-&gt;My_SysBase;

struct MyTestBase
{
  struct Library   My_Test_Lib;
	struct ExecBase *My_SysBase;
	APTR             My_SegList;
  int              testint;
};

#endif
&lt;/pre&gt;

&lt;pre&gt;
/*--------------------------------------------------------------------------*/
/* Resident header written for mytest.library */
/*--------------------------------------------------------------------------*/

#define __NOLIBBASE__

#define VERSION         1
#define REVISION        0

#define LIBHEADNAME     mytest
#define LIBHEADNAMESTR &quot;mytest&quot;
#define COMPDATE        &quot;04.10.2015&quot;
#define VERS            &quot;1.0&quot;

#define LIBBASETYPE 	struct MyTestBase
#define LIBBASETYPEPTR  LIBBASETYPE *

#include &lt;aros/debug.h&gt;
#include &lt;exec/exec.h&gt;
#include &lt;proto/exec.h&gt;
#include &lt;exec/resident.h&gt;
#include &lt;exec/nodes.h&gt;
#include &lt;exec/libraries.h&gt;
#include &lt;aros/symbolsets.h&gt;
#include &quot;lib.h&quot;

const UBYTE lib_name[] = LIBHEADNAMESTR &quot;.library&quot;;

const UBYTE lib_id[] = &quot;$VER: &quot; LIBHEADNAMESTR &quot;.library &quot; VERS &quot; (&quot; COMPDATE &quot;) by ALB42\n&quot;;

extern const APTR FuncTable[];

AROS_UFP3 (LIBBASETYPEPTR, InitLib,
    AROS_UFPA(LIBBASETYPEPTR, Base, D0),
    AROS_UFPA(BPTR, seglist, A0),
    AROS_UFPA(struct ExecBase *, sysbase, A6)
);

static struct LibInitStruct
{
    IPTR                   LibSize;
    const APTR             *FuncTable;
    const struct DataTable *DataTable;
    APTR                    InitFunc;
}
const LibInitStruct =
{
    sizeof(LIBBASETYPE),
    FuncTable,
    NULL,
    (APTR)InitLib
};

const struct Resident romtag =
{
  RTC_MATCHWORD,              /* match word */
  (APTR)&amp;romtag,              /* back pointer */
  (APTR)(&amp;romtag + 1),        /* skip pointer */
  RTF_AUTOINIT | RTF_EXTENDED,/* flags */
  VERSION,                    /* version */
  NT_LIBRARY,                 /* type of module */
  0,                          /* init priority */
  (STRPTR)lib_name,           /* module name */
  (STRPTR)lib_id + 6,
  (APTR)&amp;LibInitStruct,
  REVISION, NULL
};

AROS_UFH3 (LIBBASETYPEPTR, InitLib,
    AROS_UFHA(LIBBASETYPEPTR, Base, D0),
    AROS_UFHA(BPTR, seglist, A0),
    AROS_UFHA(struct ExecBase *, sysbase, A6)
    )
{
    AROS_USERFUNC_INIT
    
    Base-&gt;My_SegList = seglist;
    Base-&gt;My_SysBase = (APTR)sysbase;
    Base-&gt;testint = 0;
    
    USESYSBASE
    bug(&quot;InitLib\n&quot;);
    
    if (!set_open_libraries())
    {
      set_close_libraries();
      return NULL;
    }
    
    return Base;
    
    AROS_USERFUNC_EXIT
}

AROS_LH1(LIBBASETYPEPTR, LibOpen,
    AROS_LHA (ULONG, version, D0),
    LIBBASETYPEPTR, Base, 1, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    
    USESYSBASE
    bug(&quot;LibOpen\n&quot;);

    (void)version;
    
    Base-&gt;My_Test_Lib.lib_OpenCnt++;
    return Base;

    AROS_LIBFUNC_EXIT
    
}

__saveds APTR LibExpungeInternal(LIBBASETYPE *Base reg(a6))
{
  USESYSBASE
  APTR seglist;
  bug(&quot;LibExpungeInternal\n&quot;);

  if (Base-&gt;My_Test_Lib.lib_OpenCnt)
  {
    return 0;
  }

  seglist = Base-&gt;My_SegList;

  Forbid();
  Remove((struct Node*)Base);
  Permit();
  FreeMem((APTR)Base - Base-&gt;My_Test_Lib.lib_NegSize, (LONG)Base-&gt;My_Test_Lib.lib_PosSize +
    (LONG)Base-&gt;My_Test_Lib.lib_NegSize);
  
  set_close_libraries();
  return seglist;
}

AROS_LH0(BPTR, LibClose,
    LIBBASETYPEPTR, Base, 2, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibClose\n&quot;);

    if (!(--Base-&gt;My_Test_Lib.lib_OpenCnt))
    {
      return LibExpungeInternal(Base);          
    }
    return 0;
	
    AROS_LIBFUNC_EXIT
}

AROS_LH1(BPTR, LibExpunge,
    AROS_LHA(LIBBASETYPEPTR, Base, D0),
    struct ExecBase *, sysBase, 3, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT

    (void)sysBase;
    
    USESYSBASE
    bug(&quot;LibExpunge\n&quot;);

    return LibExpungeInternal(Base);
	
    AROS_LIBFUNC_EXIT
}

AROS_LH0(LIBBASETYPEPTR, LibReserved,
    LIBBASETYPEPTR, Base, 4, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;LibReserved\n&quot;);

    return 0;
    //return (APTR)LibReserved();
    
    AROS_LIBFUNC_EXIT
}


// Space for your own functions
// do not forget to update the FuncTable as well

AROS_LH1(int, TestFunction,
    AROS_LHA(int, TestValue, D0),
    LIBBASETYPEPTR, Base, 5, LIBHEADNAME
    )
{
    AROS_LIBFUNC_INIT
    USESYSBASE
    bug(&quot;TestFunction\n&quot;);

    Base-&gt;testint = TestValue + Base-&gt;testint;
    
    return Base-&gt;testint;
    
    AROS_LIBFUNC_EXIT
}

// Functable -&gt; Table of all functions in the Library, in right order - important!

const APTR FuncTable[] = 
{
    &amp;AROS_SLIB_ENTRY(LibOpen,LIBHEADNAME,1),
    &amp;AROS_SLIB_ENTRY(LibClose,LIBHEADNAME,2),
    &amp;AROS_SLIB_ENTRY(LibExpunge,LIBHEADNAME,3),
    &amp;AROS_SLIB_ENTRY(LibReserved,LIBHEADNAME,4),
    &amp;AROS_SLIB_ENTRY(TestFunction,LIBHEADNAME,5),
    (void *)-1
};

// AutoInit stuff
void *__PROGRAM_ENTRIES__symbol_set_handler_missing;
void *__LIBS__symbol_set_handler_missing;
// end of AutoInitStuff
&lt;/pre&gt;

Makefile
&lt;pre&gt;
VPATH = 
CFLAGS = -O2 -g -fomit-frame-pointer -W -Wall -Wno-parentheses
CC = i386-aros-gcc
LD = i386-aros-gcc
LDFLAGS = -nostartfiles -Wl,-Map -Xlinker linkermap
LIBS = -lautoinit -llibinit
STRIP = i386-aros-strip --strip-unneeded --remove-section .comment

OBJS = lib_header.o 

all: mytest.library

mytest.library: $(OBJS)
	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@

lib_header.o: lib_header.c lib.h

clean:
	rm -f *.o *.library *.ppu testlibrary linkermap
&lt;/pre&gt;


Porting UNIX library to AROS - dealing with static variables which would make it easy to port such libraries to AROS, keeping the benefits of sharing them on disk, but losing the benefit of actually sharing them in memory.

Our problem arises by the fact we want to share the actual code (the .text section of the library) and constant data, but we need to have per-task .bss and .data sections. If we get rid of our intention to share the .text and .rodata sections, things get quite easy: just load and relocate the library whenever it's open, by whoever it's open. It's like statically linking the library into the executable, except that the final linking is done at runtime.

In the V0 branch, in workbench/hidds/hidd.nouveau was committed pcimock.hidd. This is a pci driver that allows mocking real PCI devices under linux-hosted. The main idea is to be able to run the real hardware driver under linux-hosted with as little changes as possible (some changes will always be needed though unless someone wants to write complete device simulator) so that driver's code paths can be executed and debugged using gdb. This was a very helpful capability when porting nouveau. Now it is externalized from nouveau.hidd and can be used by other people porting drivers. The pcimock.hidd can currently mock 4 different nvidia cards, 1 AGP bridge and also mock irq.hidd.

What's the difference between this driver and the pcilinux.hidd? I used that one to develop many different HW drivers for aros. As far as I understood the intention of pcilinux.hidd it is supposed to get access to real hardware that is running under linux. The pcimock.hidd goal is to mock the hardware. For example my dev box is a PCIE system, but I still would like to run the AGP codes paths in nouveau under linux-hosted to check if they don't seg fault. The other case would be to run codes paths for hardware that the developer does not have (Fermi cards in my case). In the case of pcimock.hidd, the AROS driver's code paths will execute as long as you add proper mocking (for example fill in PCI config area or values for registers in BARs). This is an advantage for ported drivers - the code should already work (since it worked on another system) but there might have been mistakes made during porting which can be detected easily with gdb.

In case you are writing your driver from scratch, pcilinux.hidd hidd will give you more advantage, since you can actually access the real hardware from linux-hosted.


== Misc ==

===APL, MPL, BSD, GPL and LGPL Licences===

The majority of AROS sources in licensed under AROS Public License ([http://aros.sourceforge.net/license.html APL]) which (to a degree) protects us from someone taking AROS sources and not contributing improvements back (for example MorphOS took some AROS source and then contributed changes back)

It is written to allow the use of AROS code in other open source or commercial projects without exception whilst providing a mechanism so that improvements/additions can find their way back to the original source in one form or another.

There are &quot;3rd&quot; party applications used by AROS that do not fall under this license, which are an extra &quot;Contrib&quot; download for convenience.

Anyone can port GPL-ed network and sound drivers as AROSTCP and AHI are GPLed. Direct using (porting) [http://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs GPL]-ed code in other parts of AROS (gfx, sata, usb) is not possible because AROS license is not compatible with GPL. You need to utilize permissive licensed code like BSD or MIT/X11.


BSD and MPL license are the closest to APL.

APL however is not so compatible with LGPL/GPL.

LGPL case - you cannot statically combine APL code with LGPL. You can, however thank to LGPL being &quot;lesser&quot; restrictive, use LGPL dynamically loaded libraries in APL codes.

GPL case - you cannot combine APL code with GPL in any way if there is no explicit clause by GPLed code authors allowing that. If you do combine APL with GPL in &quot;bad&quot; ways described above - you have a problem (you violate GPL). This problem might result in everything in AROS becoming GPL or everything running or AROS becoming GPL (here I'm not sure really). The other scenario is that you are not allowed to legally distribute such code at all. To be honest I have grasped how to violate GPL, but I'm still no exactly sure what happens when you violate it (but I'm sure it's not anything nice)

GPL software can run on top of non-GPL &quot;system components&quot; (see system components exception of GPL), but the other way around (non-GPL using GPL) leads to problems. This means applications like scout, or Quake III are ok (in the majority of cases).

Theres no reason GPL drivers cannot be ported - but they cant be in AROS's ROM (requires linking APL code with GPL), nor can AROS depend on them (e.g. they must use existing apis).
If they are launched (dynamically linked) by a user action that is allowed. It is also allowed to distribute such binaries together for convenience.

GPL is not about statical or dynamic linking but is about executing process and function calls.


These components - SFS, isapnp, Zune texteditor, AHi, network drivers, freetype, openuirl, BHFormat, Edit and (&quot; dynamically loaded libraries&quot;) are LGPL, not GPL. Mesa/Nouveau stuff is MIT. Some user tools are GPL though.

'''AROS (system)'''
* system components (libraries/classes/devices/etc) cannot be GPL as they would propagate GPL to complete system as well as GPL is not compatible with MPL from which APL is based 
* system components can be LGPL v2 or a permissive license (MIT/BSD)
* system applications can be anything you like (but still I would prefer APL or permissive so the code can be reused if needed)

'''Contrib:'''
* no rules - contrib does not impact AROS system since nothing in AROS system depends on contrib.

About stealing code: The chances of this happening is exactly the same whether we are APL or GPL. If any closed-source option wanted to do it, there is no one that can validate otherwise. MorphOS has used some AROS codes, but contributed changes back.

The rationale behind APL is that while it guarantees that the original developer will get the improvements back (to a certain degree - file based), the person who uses the codes does not have to open his original codes. BSD does not guarantee that the original developer gets improvements. GPL requires the person using the codes to open his codes as well.

The copyright holders needs to stay - we just need information from them that the codes are available under APL (for example a checked-in file like in case of Poseidon). We don't do transfer of copyrights.

; Ultimately what can and cannot be done is up to the author(s) - not the licence.

===AROS source code tree===

* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-trunk.txt
* http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt


Found this interesting (non-GPL) licensing 'anomaly' - to keep in mind for distributors.

Programs that lose their license if sold (&quot;non-profit only&quot; licensed):
  contrib/aminet/comm/term/TinyTerminal
  contrib/aminet/dev/basic/bwBASIC
  contrib/aminet/text/edit/xdme
  contrib/fish/aroach
  contrib/fish/lotto
  contrib/fish/shuffle
  contrib/fish/touch
  + cdvdfs.


Here is a list of all the GPL/GPLv2/GPLv3 licenses fossology found, what have explicit licenses in their comments.


 excluded LGPL, BSD/GPL dual licensed and programs (such as Prefs/Edit and BHFormat)

&lt;pre&gt;
AROS/rom/dbus/include/  AFL_v2.1 ,GPL_v2+  (supposedly AFL &lt; 3 is GPL incompatible) 
AROS/workbench/classes/zune/betterstring/include/  GPL_v2+
AROS/workbench/classes/zune/texteditor/include/  GPL_v2+
AROS/workbench/classes/datatypes/gemimage/ GPL_v2+ GPL
AROS/workbench/classes/datatypes/degas/  GPL_v2+
AROS/workbench/libs/openurl/README: GPL
AROS/workbench/network/smbfs/documentation/  GPL_v2
AROS/workbench/network/smbfs/source_code/  GPL_v2+
AROS/workbench/network/stacks/AROSTCP/bsdsocket/kern/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/mmakefile.src conf.h  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/sys/  CMU ,GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/net/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/api/  GPL_v2
AROS/workbench/network/stacks/AROSTCP/bsdsocket/conf/conf.h: GPL_v2
AROS/workbench/network/stacks/AROSTCP/netinclude/net/radix.h: CMU ,GPL_v2
AROS/workbench/devs/AHI/AHI/  GPL_v2+
AROS/workbench/devs/AHI/AddAudioModes/ GPL_v2+  AROS/workbench/devs/AHI/AddAudioModes/COPYING: GPL 
AROS/workbench/devs/AHI/Docs/texinfo.tex: GPL_v2+
AROS/workbench/devs/AHI/COPYING: GPL
AROS/workbench/devs/AHI/Drivers/EMU10kx/  GPL_v2+
AROS/workbench/devs/AHI/AHI-Handler/  GPL_v2+
AROS/workbench/devs/networks/rtl8029/  GPL   GPL_v2+
AROS/workbench/devs/networks/pcnet32/  GPL   GPL_v2+
AROS/workbench/devs/networks/ppp/LEGAL: GPL
AROS/workbench/devs/networks/atheros5000/  GPL_v2+
AROS/workbench/devs/networks/rhine/  GPL_v2+
AROS/workbench/devs/networks/nForce/  GPL_v2+  GPL
AROS/workbench/devs/networks/prism2/  GPL  GPL_v2+
AROS/workbench/devs/networks/fec/LEGAL: GPL
AROS/workbench/devs/networks/rtl8139/  GPL  GPL_v2+
AROS/workbench/devs/networks/etherlink3/  GPL  GPL_v2+
AROS/workbench/devs/networks/intelpro100/  GPL  GPL_v2+
AROS/workbench/devs/networks/rtl8169/  GPL   GPL_v2+
AROS/workbench/devs/networks/emac/   GPL   GPL_v2+
AROS/workbench/devs/networks/rtl8168/  GPL  GPL_v2+
AROS/workbench/devs/networks/realtek8180/   GPL_v2+
AROS/workbench/devs/networks/via-rhine/via-rhine.c: GPL_v2+
AROS/workbench/devs/networks/via-rhine/   GPL  GPL_v2+
AROS/workbench/devs/networks/e1000/  GPL_v2
AROS/workbench/devs/networks/sis900/  GPL   GPL_v2+
&lt;/pre&gt;

AHI: it has special provisions (COPYING.DRIVERS). The library is LGPL, preferences software is GPL and drivers can be anything without breaking GPL/LGPL.

Network stack: well, we are long overdue for a new, IPv6 enabled network stack anyway, anyone interested? ;) Seriously though it seems like the glue code is GPL and as all the drivers. However some of the drivers are our own code, so they could be relicensed to LGPL.

 Same filter as the AROS trunk list. These should all be libraries or plugins - no programs.

&lt;pre&gt;
contrib/regina/utsname.h: GPL_v2+

contrib/mui/classes/nlist/include/default-align.h: GPL_v2+
contrib/mui/classes/nlist/include/amiga-align.h: GPL_v2+

contrib/mui/classes/BWins/include/MUI/BWin_mcc.h: GPL
contrib/mui/classes/BWins/include/BWin_private_mcc.h: GPL
contrib/mui/classes/BWins/COPYING: GPL_v2
contrib/mui/classes/BWins/MCC_BWins.readme: GPL_v2

contrib/mui/classes/thebar/include/default-align.h: GPL_v2+
contrib/mui/classes/thebar/include/amiga-align.h: GPL_v2+

contrib/gfx/libs/wazp3d/LEGAL: GPL
contrib/gfx/libs/wazp3d/Wazp3D.readme: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/soft3d_opengl.c: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.h: GPL
contrib/gfx/libs/wazp3d/Wazp3D-src/Wazp3D.c: GPL

contrib/libs/mpega/  GPL_v2+
&lt;/pre&gt;

http://www.evillabs.net/AROS/Audit-2012-03-14/AROS-contrib.txt

===Types===

On AROS following rules apply:
&lt;pre&gt; 
1. BYTE/UBYTE is 8bit, WORD/UWORD is 16bit, LONG/ULONG is 32bit, QUAD/UQUAD is 64bit, the types are comparable with stdint types (int8_t, int16_t, int32_t, int64_t)
2. IPTR/SIPTR are integer types large enough to fit pointer, that is sizeof(IPTR) = sizeof(APTR) = 4 on 32bit system, and = 8 on 64bit system
3. ti_Data in TagList is large enough to hold a IPTR/APTR type.
4. never store a pointer in integer of type LONG. It may work (if the pointer has upper 32bits clear), but does not have to. Compiler should warn you about that.
5. If you are unsure about point 4, allocate your memory with MEMF_31BIT flag set. But don't expect that AROS internals will do the same.
&lt;/pre&gt; 
point 4 is actually important.


* UBYTE/BYTE for 8bit
* UWORD/WORD for 16bit
* ULONG/LONG for 32bit
* UQUAD/QUAD for 64bit

&lt;pre&gt;
UBYTE    Unsigned 8 bit integer variable (byte).
BYTE     Signed 8 bit integer variable (byte).
UWORD    Unsigned 16 bit integer variable (word).
WORD     Signed 16 bit integer variable (word).
ULONG    Unsigned 32 bit integer variable (longword).
LONG     Signed 32 bit integer variable (longword).
FLOAT    32 bit IEEE floating point variable.
UQUAD    Unsigned 64 bit integer variable.
QUAD     Signed 64 bit integer variable.
DOUBLE   64bit IEEE floating point variable.
BOOL     Boolean variable, TRUE and FALSE are also defined in exec/types.h.
VOID     Void.

APTR     A generic pointer for multiple purposes - Arrays.
STRPTR   A pointer to a null-terminated string.
IPTR     Really important in AROS, the only way to declare a field that can contain both: an integer or a pointer.
&lt;/pre&gt;

if you want to write really portable app, you may be interested in standard datatypes defined in C99: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, intptr_t, uintptr_t. They are all defined in inttypes.h include file.

In exec/types.h the following short-cuts are typedef'd. They are used often in AROS, so you should nearly always include exec/types.h and soon only they will be removed from sys/_types.h include, all types are now defined in include files named aros/types/xxx.h.

(Preparation for C library split; sys/xxx.h include will only be available there when compiling with POSIX C library)


Compiler specific types, like int and long might change their size. In case of AROS, similar to linux, int remains 32 bit whereas long grows to 64 bits in size.

If you use Amiga-like data types, i.e. BYTE/UBYTE, WORD/UWORD, LONG/ULONG and QUAD/UQUAD or the C99 standard types (uint8_t and so on, see stdint.h include) then you should have less issues to solve than by using types without size guarantee.

Of course, all pointers grow to 64 bytes using 64bit cpu. Most of the code can be just recompiled and will work. In rare cases, where e.g. pointers are casted to integers, a special care must be taken. Especially in the cases, where pointer is casted to LONG/ULONG (this code will break on 64 bit AROS) e.g.  '#define IPTR ULONG'.

With compiler delint patches which the majority of them are simple casting issues to make the compiler happy. Notice some of the changes involve introducing double casts. In very recent versions of GCC. Yes, the bulk of the double casts are for converting 32 bit addresses (ie from a 32 bit PCI DMA address register) to a 64 bit pointer. First cast is to IPTR (to expand to 64 bits, and prevent sign extension if the address is above 0x7FFFFFFF), and then to APTR.

ULONG != IPTR except on 32bit .. so if you need to store pointers make sure and use IPTR and not ULONG (which some old code does). For this reason things like Taglist elements are 64bit (since the tag data can be a pointer). 
If your passing items on the stack you should use the STACKED attribute to make sure they are correctly aligned (on 64bit all items on the stack are 64bit..)

There is more issues like using &quot;== 0L&quot; causes problems.

===Endian===

*BE 
*LE

Use the macros from &lt;endian.h&gt; instead making a guess based upon architecture defines
 
&lt;pre&gt;
#if _BYTE_ORDER == _BIG_ENDIAN

#elif _BYTE_ORDER == _LITTLE_ENDIAN

#else
+
#error &lt;whatever.h&gt; - Byte order for this architecture is unsupported! 
&lt;/pre&gt;


===SVN and GIT===

If you want to help develop AROS OS itself, you can 

* view current GIT/SVN entries [http://aros.sourceforge.net/ Aros Org website] or [https://github.com/aros-development-team/AROS Github], [https://github.com/ezrec older ezrec mirror], [https://github.com/michalsc/AROS/ older mirror], [https://trac.aros.org/trac/timeline TRAC], [], 
* awaiting update [http://repo.or.cz/w/AROS.git git repo], [http://www.ohloh.net/p/aros/commits ohloh] or [https://svn.aros.org/svn/aros/trunk/ svn repo] and access [Git version git://repo.or.cz/AROS.git here], 
* deprecated [https://www.gitorious.org/aros/aros/commit/a7fda9e ARIX commits] or [https://gitorious.org/aros/aros GIT old]

If you have SVN access (early 2015 introduced a new SVN server, create a new account at trac aros org) and/or have obtained the source [http://aros.sourceforge.net/download.php AROS site] - you can compile the current build tools/environment using: 

 &gt; make development

and follow this [http://aros.sourceforge.net/documentation/developers/compiling.php#building procedure] or [https://github.com/apiraino/aros_guide Guide] 


https://trac.aros.org/trac#Developing

If you plan on contributing back changes, please post information about such changes first on this [http://mail.aros.org/mailman/listinfo/aros-dev/ mailing list] for more experience developers can validate whether they are correct.


Then there are the nightly build machines. They svn update before the build and run configure as one of the next steps. autoconf might be added to the nightly build scripts.

Our build relies on packages downloaded from Internet (SDL for example) - it always worked this way. The minimal requirement (when just building core AROS) is binutils and gcc. If you build contrib as well, you need many more packages to be downloaded.

https://gitorious.org/aros/aros/commits/crosstools-II

git://gitorious.org/aros/aros.git

Branch crosstools-II there is only one commit on top of ABI_V1 
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-x86_64
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-x86_64
&lt;/pre&gt;
and
&lt;pre&gt;
../../aros-src/AROS/configure --enable-ccache
--with-portssources=~/aros/Sources --target=pc-i386
--with-aros-toolchain-install=/home/weissms/media/data/aros/test/crosstools/pc-i386
&lt;/pre&gt;
build OK.


:''More information: [[Aros/Developer/Maintainer|AROS Maintainer Docs]]''

===SDI Calls===

Integrate the 'SDI'-headers to allow easier porting to all amiga-like platforms.

&lt;pre&gt;
PUTCHARPROTO( PutTheChar, char c, struct SPrintfStream *s  )
{
 // REAL CODE
}
&lt;/pre&gt;

have &quot;SDI_compiler.h&quot; and &quot;SDI_hook.h&quot; included

its more organized like

 #include SDI/SDI_hook.h

than

 #include SDI_hook.h

option 1 --- i also use when back porting from amiga's..

&lt;pre&gt;
#ifdef __AROS__
#include SDI/SDI_hook.h
#else
#include SDI_hook.h
#endif
&lt;/pre&gt;

also

you can add the -i include/sdi/ location if you do not want to add or edit any files.


Defining HOOKPROTO to IPTR name(struct IClass * cl, Object * obj, Msg msg); solved the problem

A MUI application most likely needs only the HOOKPROTOxxx SDI macros. They are compatible with AROS, only the attributes (hook, object attribute) must be given in the right order. examine compiler/include/aros/symbolsets.h (AROS_LIBREQ)

compiling mui stuff for aros setting -std=gnu99 is necessary (i have had -std=c99 most of the time).

===Locale with Flexcat===

Most languages have a locale, but not every app is localized, the only thing needed is to translate the &quot;catalog&quot; files. It is a case of locating the correct catalog and saving the translated version.

For every app that lacks of your language catalog and is localized anyway, you should find (in the sources) files related to locale:

* file.cd = catalog descriptor, contains base msg, with internal language (usually english)
* language.ct = catalog translation, contains every translated msg, indexed as in the file.cd.

Compare with other localized apps... Then, &quot;make my_app-catalogs&quot; should create and install your translated catalogs. ex : for, saying, sys:prefs/wanderer:

on root of AROS sources, type:
 &quot;make workbench-prefs-wanderer-catalogs&quot;
then (if you changed the .cd file):
 &quot;make workbench-prefs-wanderer&quot;

For apps not localized, you have to adapt their code to support it, if it is possible...

noticed the original .cd file has many (//) strings at the end of any voice, so added them also to the .ct file. 
That (//) is only for cd files. I'm highly recommending to use FlexCat for updating ct files, e.g. like this:

 flexcat app.cd deutsch.ct newctfile deutsch.ct

You'll get error checking and new entries are marked in the resulting ct file.

When editing .ct files, only change those lines containing translation and perhaps version string, nothing else.
The rest is up to the relevant tool, flexcat. In order to update your translation, type in the following in your shell:

 flexcat xyz.cd xyz.ct NEWCTFILE xyz_upd.ct COPYMSGNEW

This way you will not only make sure you have correct translation file but flexcat also pre-fills newly added strings with &quot;*** NEW *** text. Even better tool for checking cd/ct/catalog files is catcheck, but this one is sadly only available for AmigaOS/68k...

Some languages have variations, like portugues from portugal and portugues from brasil differs...

This is the way to go. I will have a look at language files, but basically if those two languages differ you have to do two separated set of translation files, yes.
(you could create a brazilian slang language localization too)

* At system level localization for one language is a dot language file.
(ex: locale:languages/klingon.language)

* At app level localization is a dot catalog file
(ex: locale:catalogs/klingon/system/libs/dos.catalog)

* At sources level, the dot ct file, and &quot;$language&quot; dot cd files and some building framework.
(ex: catalogs/my_app.ct catalogs/klingon.cd catalogs/mmakefile.src support.c support.h)

Please, use Flexcat to generate CT files: 
 FlexCat wanderer.cd NEWCTFILE=deutsch.ct

Then fill the first 2 lines with something useful:
&lt;pre&gt;
## version $VER: wanderer.catalog 1.1 (9.2.2006)
## language deutsch
&lt;/pre&gt;

You can even update the CT-File: (This adds the new strings)
 FlexCat wanderer.cd deutsch.ct NEWCTFILE=deutsch.ct


To compile a catalog you only need the .cd file and your translation (.ct file):
 FlexCat multiview.cd deutsch.ct CATALOG=MultiView.catalog


[http://murks-ide.svn.sourceforge.net/viewvc/murks-ide/trunk/src/Catalogs/flexcat_linux?revision=100 Linux version of FlexCat]

: [http://aros.sourceforge.net/documentation/developers/app-dev/localization.php#localization-for-non-developers More information]


A script which compares the required version (i.e. the version which an application/module etc. tries to open) with the version of the existing CT files. The result is in this table:

https://github.com/aros-translation-team/translations/wiki/Progress

The following cases are highlighted:

    n/a i.e. CT misses at all
    version in existing CT file is lower than the required version


It might be a bit difficult to participate if you haven't worked with Git before but alternatively you can send your CT files to our Slack channel.

When the ct file has been generated via flexcat (flexcat keyshow.cd NEWCTFILE=spanish.ct) it has the following header:

---------------------------------------------------------------------------------------------------------------
## version $VER: &lt;name&gt;.catalog &lt;ver&gt;.&lt;rev&gt; (04.01.2021)
## language nolanguage
## codeset 0
;
---------------------------------------------------------------------------------------------------------------

Those values &lt;ver&gt;.&lt;rev&gt; are the version and revision of the CT file for the languaje or are the values of the application being localized?

The &lt;ver&gt; part must match with version which the application tries to open. You can find the value either in the column &quot;Required Version&quot; in the table which I've linked above, our you can look in the git repository. For keyshow it would be https://github.com/aros-translation-team/keyshow. You can find in the file &quot;catalog_version.h&quot; the right version number.
The &lt;rev&gt; part starts for new CT files with 0 and should be increased every time the CT file is updated.

Updated several files and created a few more that were missing on the spanish catalog.

The catalogs are in Git repositories at https://github.com/aros-translation-team

a) You tell me your Github user name. I'll invite you. You can work directly with the Git repositories.

b) You create Github forks of the catalog repositories and create pull requests.

c) You send the CT files to mrustler  gmx de


===C Utils Misc===

The AROS source uses at several places the __DATE__ macro to fill the date entry of a $VER tag. Problem is that c:version doesn't understand that date format (e.g. &quot;May 21, 2011&quot;). As a result the output of e.g.
&gt; &quot;version c:shell full&quot; contains &quot;(null)&quot;. Is extending the version command to understand the format of __DATE__  the right solution for that problem?

AmigaOs compilers should use __AMIGADATE__ macro or similar form, if it isn't implemented it could be emulated in makefile: -D__AMIGADATE__=\&quot;$(shell date &quot;+%d.%m.%Y&quot;)\&quot;

BTW. I think DD.MM.YYYY is better format than &quot;Month DD YYY&quot; because &quot;Month DD YYY&quot; is not localized in any way.

&quot;strnicmp&quot; shouldn't work with NULL pointers

The Situation:

compiled a linklib using c++ object files (using the c++ cross compiler).
compiled a C stub that uses the linklib (using the c++ cross compiler).

Try to link them together (using the c++ cross compiler) with C object
files (using the normal target c compiler) that need to use -nostartup
= cant do because using the c++ files pulls in arosc (for stdio etc.) -
so wants to have the autoinit stuff present.

What can I do about this??

If it is possible to manually open it then what do I need to do exactly?

=== ENV ===

The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact. However in some cases (like this one) it is not required.

99% of the time that statement is true (not required) for pretty much every file in ENV: or do people change their default icons - and prefs settings - every boot?

There seem to be a bad habit of late with developers changing things to reflect their own personal preference when the change isn't actually necessary - It would be nice if people could refrain from doing that in the tree without at least discussing it on the dev-list first (and with good reasoning unless they committed said work in the first place..)

We're not keen on the pollution of the &quot;S:&quot; dir: it's meant to be for scripts. What's wrong with &quot;ENV:&quot;?
Only the fact that it takes up RAM. I  understand  that  for  PCs  with  several gigabytes of RAM this is
irrelevant. But let's remember about other machines. The philosophy behind ENV: is that keeping configuration files there allows you to  'Use'  preferences  by  keeping  a copy in ENVARC: intact.

However in some cases (like this one) it is not required.

How about implementing in the style of HappyENV then? RAM-disk handler that falls through to reading from ENVARC: if there is no such file stored in it already. Removes RAM usage for unchanged files, removes the need to copy ENVARC to ENV in startup-sequence. 
Shouldn't be too hard to make from AmberRAM, or even just extend AmberRAM to provide this service.

Is it feasable to build a special version of AmberRAM handling ENV: that will try and copy the requested file from ENVARC: if it isnt found in ENV: ? 
Additionaly it could mark closed &quot;files&quot; as untouched - and expunge them from ENV: after a period of time to free up additional RAM:, or when the system is running low on free memory?

Silenty disappearing files may not be a good plan. Would be nice if the following would work:

ASSIGN :ENV SYS:Prefs/Env-Arc ADD
ASSIGN :ENV RAM:ENV  ADD

Where new files put in ENV: end up in RAM:ENV, and opening files looks in RAM:ENV first, then SYS:Prefs/Env-Arc

Well - that's essentially what im proposing but without the assigns - or need for a RAM:ENV directory. 
Adding it as a feature of AmberRAM sounds like the most memory efficient way (one handler to load in RAM) but that's only if it is possible to make it handle ENV: additionally to RAM:, and if it is even possible to add the proposed functionality (...and how to make it enable it when accessing ENV:).

===(AS)MP support===

If one has to recompile software for SMP multi core, is there any thing special one has to do to get software to run?   
Use task.resource if you need to query information about what tasks are running, and clear msgports completely when they are allocated.

Most code should not need Forbid. Use Semaphores, Messages etc. to sync your own code. 

Accessing system structures is a different thing. Use the proper API whenever possible.

How single structures will be protected in the future is still a moving target, at least it is not documented. And you should never  use undocumented stuff  


Ideas on for SMP multi-core

Another suggestion is ... Forbid/Permit function calls are meant to halt multitasking so as no other task could intervene with what ever the calling task is doing, e.g. setting semaphores. Disable/Enable calls are meant to halt interrupts and as a side effect they also halt task switching.

One option is to make it compulsory to protect shared resources with semaphores and forbid the use of simple Forbid() calls as to protect something. Setting semaphore should be done if possible with atomic instructions (check and alter in one instruction). Or make the second concurrent ObtainSemaphore call halt the second calling task and force if possible a task switch which ever gives better results. 

Semaphores could store the owning tasks task pointer instead of boolean to make things easier.

As long as the CPU initiates the DMA transfers through the OS, and the OS ensures that the transferred memory is within the region accessible to the user initiating the transfer, everything is fine. The CPU is the conductor, and the CPU by that has the control of which DMA transfer is initiated and which is not.
All you need to do is to write device drivers reasonable. Hint: CachePreDMA and CachePostDMA exist.
All the Os has to do is to verify that the memory regions to be transferred are valid, and prohibit direct access to the DMA control registers from user space. None of these algorithms imply huge costs.
The current OS design doesn't really allow virtual memory in first place, Forbid() is again the problem.

[http://www.tbs-software.com/guide/index.php?guide=autodocs.doc%2Fmemory.doc&amp;node=1 memory.library API] seem to low level. IMHO the programs should not know how the swapping is implemented. I would just go for one new memory flag
MEMF_SWAPPABLE that indicates that a certain memory region or a whole memory pool won't be accessed during Forbid()/Permit() etc. It only solves part of the problem, it only implements virtual memory and not memory protection. For the latter you need to be able make certain memory inaccessible by other programs, some memory read-only for one task and read-write for other tasks, etc. And I think this should be done in the same Address Space in order to avoid you constantly need to swap between different address spaces. 
So to summarize, if there are programs using this API we may provide a wrapper layer to get them working but I am not convinced this API should be the reference API with whom to provide VM to AROS programs.

=== Variadic ===

variadic functions (i.e. functions with an arbitrary amount of arguments).

&lt;pre&gt;
    #include &lt;stdarg.h&gt;
    [...]

    char * STDARGS GetKeyWord(int value, char *def, ...)
    {
        [...]
        va_list va;
        [...]
        va_start(va, def);
        [...]
        va_end (args);

&lt;/pre&gt;

Please keep with using stdarg rather than having va casted to a LONG * type and varargs handled manually. Doing so, prevents tons of casting, where a simple va_arg can be used. So, string = *((char **) args) instead of string=va_arg(va, char *).

&lt;pre&gt;
#include &lt;stdio.h&gt;
#include &lt;stdarg.h&gt;

int printf (const char * format, ...)

{
    int     retval;
    va_list args;

    va_start (args, format);

    retval = vfprintf (stdout, format, args);

    va_end (args);

    fflush (stdout);

    return retval;
} /* printf */
&lt;/pre&gt;

Couldn't find varargs.h or stdarg.h. and have no use for AROS_SLOWSTACKHOOKS or AROS_SLOWSTACKTAGS.

GCC looks for stdarg.h in a different place: 
 /bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/include/stdarg.h

Here is a path for a &quot;normal&quot; header:
 bin/linux-i386/tools/lib/gcc/i386-aros/4.2.2/../../../../i386-aros/sys-include/aros/system.h


The use of vararg.h isn't supported by newer gcc versions. If you want your code to run on architectures that pass part of variadic arguments in a number of registers you need to use AROS_SLOWSTACK macros. Otherwise your program will not work on powerpc and x86_64 ports.

Of course the SLOWSTACK stuff is not needed in a function that can use va_list, va_start, va_arg and va_end. It's only needed if you want to write functions like DoMethod or similar.

 #include &lt;stdarg.h&gt;

should be enough no matter if you do cross or native compiling. If it does not work, something is wrong and should be corrected.

Stdarg.h is here, Development:lib/gcc/i386-aros/4.2.2/include/

...which is part of the compiler's default include paths. In other words, #include &lt;stdarg.h&gt; works out of the box, indeed. (sorry, I should have just tried it before invoking &quot;search&quot; or &quot;find&quot;...)

furthermore, myprintf() as shown above won't work, because...

 printf(format, args);

...is wrong - the second argument does not match printf() prototype, it expects a argument list, but args is of type va_list (obviously) - so one has to use...

 vfprintf(stdout, format, args);

...instead, just like in the original printf(), and add fflush(stdout).

additionally, one could use...

 int myarg = va_arg(args, int);

...between va_start() and va_end() to access individual arguments, where each call to va_arg() returns an argument casted to the desired type (here: &quot;int&quot;) from the list given (here: &quot;args&quot;) and advances to the next one.

wrapping up vfprintf() and modifying the format string now is a major speedup! no more backslash-n typing! this has been haunting me for years!

On MOS and AmigaOS, the NewObject variadic function is kept in the static library. It takes most of the parameters on the stack - thanks to that the implementation of NewObject calls the NewObjectA function. Everything works perfect, and the typical MUI macros may be easily used.

This, however, is not the case when you compile for AROS. Here, NewObject is a variadic macro, not a function. Thanks such approach we do not need any custom compiler in case of systems, where the arguments of variadic functions are passed partially through registers and partially through the stack (This is the case of PPC and x86_64, this is also the reason why both OS4 and MOS require specially patched compilers).

Since NewObject is a macro, the gcc's preprocessor expects the list of macros arguments enclosed within parentheses. In MUI macros it is not the case. Imagine the following test code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))

int loosy_function(int a, int b)
{
    return foo(a,b);
}
&lt;/pre&gt;

This will compile and work, but the following piece of code:

&lt;pre&gt;
#define foo(a,b) ((a)+(b))
#define END )

int loosy_function(int a, int b)
{
    return foo(a,b END;
}
&lt;/pre&gt;

will fail with the error: unterminated argument list invoking macro &quot;foo&quot;

There are two ways of fixing your issue. Either create your new objects outside this huge MUI constructions, and in there use just a pointer, or get rid of the &quot;End&quot; macro and exchange it with &quot;TAG_DONE)&quot;.


Badly written software is, for example, casting va_list to an APTR or even doing so as if va_list were a plain table of function arguments. Such code needs to be fixed because it has very few chances to work anywhere but on author's machine ;)

The problem is nOt that they assume sizeof(APTR) == 4, its that they often do not use APTR, and use ULONG to store pointers exclusively. If the code used APTR/IPTR as it should - most of the &quot;problems&quot; wouldn't exist.

It would also help if people would start using variadic arguments properly. Many coders do assumptions which shall never be made. Instead, they should consider using stdarg.h file and all the va_* functions :)

===ABI===

In the head of our SVN repository there are now only 3 directories:

&lt;pre&gt;
admin/
branches/
trunk/
&lt;/pre&gt;

We have added two extra dirs there: tags and imports

As discussed when we branch ABI V0 and [[Aros/Developer/ABIv1|ABI V1]] it would also be good to introduce tags. Normally this is done in a directory in the repository called tags. Currently we don't have this directory there. (We do have branches/tags that is a hack I have done because one doesn't have write access in the top directory. I think this directory is not clean and should be removed).

The second directory I would introduce is an imports directory for implementing vendor branches as discussed in the svn [http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html book]. Currently we use code from several different projects and that code is stored inside the AROS tree; we seem to have problems with keeping this code up to date and merge our changes upstream. Maintainers of up stream projects like the MUI classes etc. have complained about this (to put it lightly).

Introducing these vendor branches would make it easier to see what changes we have made and make patches to be sent upstream and make it easier to import newer upstream versions of their code. Although can't &quot;copy&quot; the vendor branch into the main branch because it's already there, so start with a &quot;merge&quot;.

Yes, the first step to make the code already in the repository compatible with the vendor branches will be the most difficult. The best way to do it the following way:

* first import the version on which the current AROS code is based into the vendor branch
* then import the new version over it in the vendor branch
* finally merge the difference between these two version in the AROS code present in the repository.

For example, place NList directly under vendor and not in a subdirectory like &quot;contrib/zune/classes&quot;.

Actually after we have a stable [http://aros.sourceforge.net/documentation/developers/specifications/drafts/abiv1.php ABIv1 (2012 or later)]. We need to move away as much as possible from the contrib directory to some other repositories. The reasons are ...

* The AROS repository should be for the core AROS code.
* other contrib projects should be tried to be compiled for all Amiga-like OSes.
* The release scheme for AROS and the other programs should not have to be aligned.
* Binary versions should be provided on aros-archives and on aminet and/or OS4Depot to install them. (Some clever programs should maybe be provided to make the life of distribution developers easier). 
* avoid parallel forks of programs for AROS and the other amiga OSes.

If there is really a need for a place for hosting AROS projects we may investigate setting up such a server but then including bug tracking, governance, maillist, etc. for each project separately. I personally think there are already enough places like sourceforge, google code, savannah, etc. where people can go for hosting such projects.

==Links==

* http://amigadocs.hokstad.com
* http://amigadocs.hokstad.com/doku.php?id=dev-links


 In the future...?
*AROS 64bit - SMP, Vulkan with OpenGL compability layer
*AROS 32bit - keep for historic reasons 

What would you like to see implemented in AROS?
ABIv1 completed, SMP (x86_64),  SendMsg()/GetMsg() to support memory protection between target and destination, in that order.   Michal Schulz and Jason McMullan have been toying with the question &quot;What are the minimal changes needed to the AmigaOS 3.1 API to support SMP&quot;?  The answer so far seems to be &quot;few, but subtle&quot;.  For example, SysBase-&gt;ThisTask is no longer meaningful on SMP, but FindTask(NULL) is.  Disable() and Forbid() are shockingly bad on performance, but adding a spinlock semaphore mode to SignalSemaphore will help new code on SMP.  

Leveraging a 'common' OS with a lot of machine support (Linux, MacOS, Windows, QNX, etc.) is something that AROS has been doing for quite a long time, and it is the biggest strength of AROS. This AROS experience and programming model, in the same way the Google's Android layers on top of Linux, or MacOS X layers on top of the Darwin/BSD kernel, as a first step 

* The graphics + layers subsystem could be implemented as a shim on top of a OpenGL ES implementation (ie on any modern Linux system, or the RaspberryPI's hardware, MacOS X, etc). 
  - This also allows every window to be on its own 3D surface with backing store, allowing Wanderer (or a Commodity)
rearrange/zoom/animate app windows without having to send a pile or refreshes to them

* Use OpenAL as the sound backend
* AROSTCP would be a thin layer over the native OS's TCP/IP stack
* dos.library, poseidon.library, and input.device would be slim shims over the native APIs
* If we move to loading all libraries' into the application's task space, instead of a single global instance of the library, this will allow SMP and MMU more easily. 
  - Yes, it will require a lot of work in the libraries to make this transition
  - Yes, I do think it will be worth it in the end.

* A 'fat binary' install format (or, maybe LLVM bytecode) that can be 'flattend' to the target architecture on installation.

So, what would this 'AROS of the future' look like?

* AmigaOS 3.x style API, with certain 'fundamental changes' to message passing
* Uses the underlying OS' device drivers, so more AROS developer effort can go to user-visible features and bugfixes 
* Allows AROS applications to run side-by-side with the OS's native apps


And why would anyone want to program on such a system?

* AROS applications would run on any system that has the AROS Framework installed
* AROS applications are pixel-for-pixel the same on all platforms. 
* Develop with the knowledge that you are guaranteed OpenGL and OpenAL, and the rest of the AROS Framework

an option for mmake to dump its dependency of metatarget in a graphviz[*] input file. This should make it possible to visualize the dependencies and hopefully be inspiration for cleaning up some mess, circular or unneeded dependencies and so on.


AmigaOS gcc 9 [https://franke.ms/amiga/gcc.wiki Old versions] able to create binaries for AmigaOS and [https://eab.abime.net/showthread.php?t=93813 Upgrading gcc versions] 


=== AI ===

Please see discussion of the [https://arosworld.org/infusions/forum/viewthread.php?thread_id=1933&amp;rowstart=0 Aros world thread] [https://opencode.ai/ opencode], [https://openrouter.ai/models?categories=programming new opencode models], [https://axrt.org/media/aros-ui-ai.mp4 AI ui], 

*DeepSeek V4 Flash - very good model, use it daily but a small monthly fee payable 
*Ring 2.6 - good model but pricing small                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   


                  Multimodal
                   Context
                   Prompt
                    &lt;---
  Model &lt;---&gt; Agent ---&gt; End user
 engine 

 Gemini      LMStudio
  Qwen       Comfyui
   etc


Recent, self hosting local models on laptops, mini pcs, laptops or desktops with '''quantization''' (compressed) so reducing memory to run on 8Gb+ VRAM and no high end gpu for text based tasks. For smaller models, very specific prompting and chatting (iterations) for very smaller sections of your overall application as lots of supervision needed for the code produced 

Ability increases by the amount of ram like the Pi5 8Gb, Macbook 48Gb unified (quality) and the memory bandwidth (how fast) 

Roughly...
*DDR4 Pi5    about 17GB/s 
*DDR5        about 40Gb/s 
*DDR6        about 90Gb/s about Jetson Orin Nano level 
*Strix Halo  about 210Gb/s 
*DGX Spark   about 220Gb/s
* MacBook M3 base 100GB/s Pro 150GB/s Max 200Gb/s unified memory integrated into CPU 
* MacBook M4 base 120Gb/s Pro 170Gb/s Max 250Gb/s 
* MacBook M5 base 140Gb/s 
* MacBook M6 base 160Gb/s Pro 180Gb/s Max 


Total VRAM should be greater than Model size (in Gbytes), context length (you set Gbytes taken) and KV cache - everything is a trade off 

&lt;pre&gt;
Small   Lesser  Mid   Greater  Bigger 
 1-2B     3B     7B     20B     30B     model size 
  Q2      Q2     Q4     Q6       Q8     compressing 
 4GB     8GB    16GB   32GB     64GB    VRAM needed 
&lt;/pre&gt;


*[https://lmstudio.ai/download LMstudio single gpu],

 128Gb 
*[ gpt-oss-120b] 70Gb model  

 64Gb 
*[HauHau 3.6 35B] 

*[ muse-glimmer]

 32Gb 
Alibaba Cloud's [ Qwen] team series of large language models LLMs 
*[ Qwen-3.8-27B] 
*[ Qwen-3.6-27B] 

 16Gb
*[ Qwen 3.8 27B GSQ ACO GGUF]

 8Gb 
*[ glm-ocr]
*[ medGemma]
*[ qwen 3.5-4b]
*[https://github.com/sipeed/picoclaw picoclaw claude] 
*[ DeepSeek R1] 
*[ Qwen 3.5 9B Q4] 
*[ Qwen 2.5 14b Coder] 
*[ gpt-oss-20b 4Q] 


For the full experience 
#Training learning using 1+ high end GPUs at least 16GB VRAM per GPU card or 64Gb+ of unified, 16Core CPU with at least 64Gb of RAM system memory 
#Inference with custom asics or GPUs 


For ever bigger LLMs needs one of the below but with settings adjusting 
*[https://ollama.com/download Ollama single gpu]
*[https://github.com/ggml-org/llama.cpp/releases llama.CPP multi gpus],
*[ VLM multiple gpus], 


*[ MiniMax H3] for audio and video but gpu 8Gb+ 
*[https://github.com/ideogram-oss/ideogram4 ideogram4]
*[https://github.com/calesthio/OpenMontage OpenMontage]

*[https://github.com/jamiepine/voicebox voicebox]
*[ Chatterbox] with neural watermark 
*[ Index-TTS] 
*[ Qwen3-TTS]
*[ Omnivoice]
*[ faster-qwen3]
*[ dots.tts]


Multimedia 
*[ Kimi K3], 


 Refactor 
*[ Devstral-small-2 256K context] 


 FIM - Fill in the middle 
Mistral Codestral-2 for 64Gb+ unified 


&lt;pre&gt;
Text to Audio --\
Text to Video --/ Reference Video --&gt; Video and Audio output 
&lt;/pre&gt;


 Agent = Model + Harness 

 Agentic 

Harnesses like [ Claude Code] [ Cursor] [ ] could help models. [https://github.com/deepseek-ai/deepseek-harness Deepseek] etc allows many models to reside inside but also everything is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration 


==References==
{{reflist}}
{{status|50%}}

{{BookCat}}</text>
      <sha1>fpgkgpjra6qamnhneluycw6ekyfkvw9</sha1>
    </revision>
  </page>
  <page>
    <title>Chess Opening Theory/1. e4/1...e5/2. Nf3/2...Nf6</title>
    <ns>0</ns>
    <id>37085</id>
    <revision>
      <id>4669874</id>
      <parentid>4635184</parentid>
      <timestamp>2026-09-13T09:48:15Z</timestamp>
      <contributor>
        <username>Enbi</username>
        <id>3570561</id>
      </contributor>
      <comment>/* Theory table */ 0-0 -&gt; O-O</comment>
      <origin>4669874</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="7013" sha1="apqdvi19prm8ev03ioeggapeyajl01r" xml:space="preserve">{{Chess Opening Theory/Position
|Russian game
|parent=[[../|King's knight opening]]
|eco=[[Chess/ECOC|C42-43]]
|responses=&lt;br&gt;
* [[/3. d4|3. d4 · Modern attack]]
* [[/3. Nxe5|3. Nxe5 · Classical variation]]
* [[/3. Bc4|3. Bc4 · Italian variation]]
* [[/3. Nc3|3. Nc3 · Three knights]]
}}
== 2...Nf6 · Petrov's defence or Russian game ==
Rather than defend e5, Black counterattacks e4. This is the Russian game, aka Petrov's or Petroff's defence, a solid if drawish opening.&lt;ref&gt;60% of games in the Lichess masters database result in draws, compared to 50% for 2...Nc6.&lt;/ref&gt; 

White's typical plan is to attack the centre, usually leading to a trade of pawns. Alternatively they may gambit their e4 pawn, or defend it and perhaps hope for a transposition. 

=== Trade e pawns ===
[[/3. Nxe5|'''3. Nxe5''']] is the main line, the '''Classical variation'''. As Black didn't defend their pawn, White takes it. Black can recover it, but not immediately on account of dangerous tactics resulting from 3...Nxe4!? 4. Qe2!, exploiting the open e-file (including the famous trap, 4...Nf6?? 5. Nc6+ winning the queen). The best line is 3...d6, chasing White's knight away, after which 4...Nxe4 is safe because if 5. Qe2 Qe7 defends the knight. 3...Nc6?!, the aggressive Stafford gambit, is the most common reply in amateur games. Black gives up a pawn for open lines and a sharp attack. 

[[/3. d4|'''3. d4''']], the '''Modern attack''', was advocated by [[wikipedia:Wilhelm Steinitz|Steinitz]].&lt;ref name=&quot;steinitz&quot;&gt;{{Cite book |title=Modern Chess Instructor |last=Steintiz |first=Wilhelm |publisher=G. P. Putnam's Sons |year=1889 |location=London |pages=116-139}}&lt;/ref&gt; Of the two captures, 3...Nxe4 is most common. 3...exd4 is playable but after 4. e5 Black falls behind while their knight gets kicked about (4...Ne4 5. Qxd4 d5 6. exd6 Nxd6{{Chess/not|+}}).

=== Gambit e4 ===
[[/3. Bc4|'''3. Bc4?!''']], the '''Italian variation''', leaves White's e4 pawn undefended. It's usually played with the idea of sacrificing it for development: 3...Nxe4 4. Nc3?!, the  Boden-Kieseritzky gambit. Instead, 3...Nc6 transposes into a Two knights defence of the Italian game. 

=== Defend e4 ===
White may wish to prevent ...Nxe4, though taking the time to defend their pawn gives Black the chance to defend theirs too. 

[[/3. Nc3|'''3. Nc3''']], the '''Three knights variation''', is a sound sideline. White develops a piece and invites Black to transpose to a '''Four knights''' with 3...Nc6 and avoid the Petrov  main lines. 3...Bb4 avoids transposing, pressures the knight on c3 and makes the game a little more active.

[[/3. d3|'''3. d3''']] is, according to statistics, much more effective than it looks. White builds a strong fortress and Black must now defend his pawn. The game usually ends up looking like [[Chess Opening Theory/1. e4/1...e5/2. Nf3/2...d6/3. d4/3...Nd7|a Hanham variation of the Philidor]] with colours reversed (3...Nc6 4. Be2 d5 5. Nbd2 Bc5 {{Chess/not|-}}) or White adopts a King's Indian attack-style setup with g3 and Bg2.

=== History ===

2...Nf6 is a very old opening, appearing in the 15th/16th century [[wikipedia:Göttingen manuscript|Göttingen manuscript]], the earliest manuscript dedicated to modern chess. 

However, it was largely overlooked until the 19th century. Jaenisch (1813―1872) levels (his typical, bombastic) criticism at previous attempts to characterise the opening in his 1842 book&lt;ref name=&quot;jaenisch&quot;&gt;{{Cite book |title=Jaenisch's chess preceptor: a new analysis of the openings of games |last=de Jaenisch |first=C. F. |publisher=Longman &amp; co. |year=1847 |location=London |url=https://babel.hathitrust.org/cgi/pt?id=hvd.hn52dv&amp;seq=5 |translator-last=Walker |translator-first=George}} (translation of {{Cite book |title=Analyse nouvelle des ouvertures du jeu des échecs |last=de Jaenisch |first=C. F. |publisher=Gartner |year=1842}})&lt;/ref&gt;{{rp|126-147}}:

&lt;blockquote&gt;The fate of this opening has been somewhat &quot;bizarre.&quot; Proclaimed faulty from the 16th century (compare [[wikipedia:Pedro Damiano|Damiano]], [[wikipedia:Ruy López de Segura|Lopez]], and Gianutio), it has been entirely thrown on one side, and has only since appeared in the books; which content themselves with reproducing, without change, the ancient analysis of the classics. [[wikipedia:Carlo Cozio|Cozio]], in truth, that frivolous genius, who saw everything superficially, without diving into it, at last briefly corrected the fallacies of the original analysis in question; but, curious enough, was not himself aware of the importance of his observation, which passed altogether unnoticed by later writers.&lt;br&gt;—Carl Jaenisch (translation: Walker)&lt;ref name=&quot;jaenisch&quot; /&gt;&lt;/blockquote&gt;

It was [[wikipedia:Alexander Petrov (chess player)|Alexander Petrov]] (1794―1867) and Jaenisch's analyses that led to the rejuvenation of opening in the 19th century (and it's after these two Russians the opening gets its appellation). Jaenisch highlights Petrov's independent (re-)discovery of Cozio's 3. Nxe5 d6! (over 3...Qd7).&lt;ref name=&quot;jaenisch&quot; /&gt; 

Jaenisch also credits Petrov with 3. d4 as White,&lt;ref name=&quot;jaenisch&quot; /&gt; the line later advocated by [[wikipedia:Wilhelm Steinitz|Steinitz]] in his 1889 book.&lt;ref name=&quot;steinitz&quot; /&gt;

==Theory table==
{{Chess Opening Theory/Table}}

'''1. e4 e5 2. Nf3 Nf6'''
&lt;table border=&quot;0&quot; cellspacing=&quot;0&quot; cellpadding=&quot;4&quot;&gt;
	&lt;tr&gt;
		&lt;th&gt;&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;3&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;4&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;5&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;6&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;7&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;8&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;9&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;10&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;11&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;12&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;13&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;14&lt;/th&gt;
		&lt;th align=&quot;left&quot;&gt;15&lt;/th&gt;
	&lt;/tr&gt;
	&lt;tr&gt;
		&lt;th style=&quot;text-align:right;font-size:small;&quot;&gt;Classical Variation&lt;/th&gt;
		&lt;td&gt;[[/3. Nxe5|Nxe5]]&lt;br&gt;d6&lt;/td&gt;
		&lt;td&gt;Nf3&lt;br&gt;Nxe4&lt;/td&gt;
		&lt;td&gt;d4&lt;br&gt;d5&lt;/td&gt;
		&lt;td&gt;Bd3&lt;br&gt;Nc6&lt;/td&gt;
		&lt;td&gt;O-O&lt;br&gt;Be7&lt;/td&gt;
		&lt;td&gt;c4&lt;br&gt;Nb4&lt;/td&gt;
		&lt;td&gt;Be2&lt;br&gt;O-O&lt;/td&gt;
		&lt;td&gt;Nc3&lt;br&gt;Bf5&lt;/td&gt;
		&lt;td&gt;a3&lt;br&gt;Nxc3&lt;/td&gt;
		&lt;td&gt;bxc3&lt;br&gt;Nc6&lt;/td&gt;
		&lt;td&gt;Re1&lt;br&gt;Re8&lt;/td&gt;
		&lt;td&gt;cxd5&lt;br&gt;Qxd5&lt;/td&gt;
		&lt;td&gt;Bf4&lt;br&gt;Rac8&lt;/td&gt;
		&lt;td&gt;=&lt;/td&gt;
	&lt;/tr&gt;
	&lt;tr&gt;
		&lt;th style=&quot;text-align:right;font-size:small;&quot;&gt;Steinitz Variation&lt;/th&gt;
		&lt;td&gt;[[/3. d4|d4]]&lt;br&gt;Nxe4&lt;/td&gt;
		&lt;td&gt;Bd3&lt;br&gt;d5&lt;/td&gt;
		&lt;td&gt;Nxe5&lt;br&gt;Nd7&lt;/td&gt;
		&lt;td&gt;Nxd7&lt;br&gt;Bxd7&lt;/td&gt;
		&lt;td&gt;O-O&lt;br&gt;Bd6&lt;/td&gt;
		&lt;td&gt;c4&lt;br&gt;c6&lt;/td&gt;
		&lt;td&gt;cxd5&lt;br&gt;cxd5&lt;/td&gt;
		&lt;td&gt;Nc3&lt;br&gt;Nxc3&lt;/td&gt;
		&lt;td&gt;bxc3&lt;br&gt;O-O&lt;/td&gt;
		&lt;td&gt;Qh5&lt;br&gt;g6&lt;/td&gt;
		&lt;td&gt;Qxd5&lt;br&gt;Qc7&lt;/td&gt;
		&lt;td&gt;=&lt;/td&gt;
	&lt;/tr&gt;
	&lt;tr&gt;
		&lt;th align=&quot;right&quot;&gt;[[Chess/Two Knights Defence|Two Knights Defence]]&lt;/th&gt;
		&lt;td&gt;[[/3. Bc4|Bc4]]&lt;br&gt;Nc6&lt;/td&gt;
		&lt;td&gt;=&lt;/td&gt;
	&lt;/tr&gt;
	&lt;tr&gt;
		&lt;th align=&quot;right&quot;&gt;[[Chess/Four Knights Game|Four Knights Game]]&lt;/th&gt;
		&lt;td&gt;[[/3. Nc3|Nc3]]&lt;br&gt;Nc6&lt;/td&gt;
		&lt;td&gt;=&lt;/td&gt;
	&lt;/tr&gt;
	&lt;tr&gt;
		&lt;th style=&quot;text-align:right;font-size:small;&quot;&gt;&lt;/th&gt;
		&lt;td&gt;[[/3. d3|d3]]&lt;br&gt;Nc6&lt;/td&gt;
		&lt;td&gt;=&lt;/td&gt;
	&lt;/tr&gt;
&lt;/table&gt;
{{ChessMid}}

==References==
{{reflist}}
=== See also ===
{{wikipedia|Petrov's Defence}}
{{BCO2}}
{{Chess Opening Theory/Footer}}</text>
      <sha1>apqdvi19prm8ev03ioeggapeyajl01r</sha1>
    </revision>
  </page>
  <page>
    <title>Guitar/Scales</title>
    <ns>0</ns>
    <id>40925</id>
    <revision>
      <id>4669792</id>
      <parentid>4475854</parentid>
      <timestamp>2026-09-13T02:23:41Z</timestamp>
      <contributor>
        <username>Mjchael</username>
        <id>44398</id>
      </contributor>
      <comment>/* Three scale concepts at a glance */</comment>
      <origin>4669792</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="20749" sha1="my6sn77ysg7e7weifgtc6vp0gbm1bi6" xml:space="preserve">[[File:Apollo Musagetes Pio-Clementino Inv310.jpg|thumb|The god of music Apollo strumming a lyre. In Greek mythology the lyre was invented by Hermes who presented it to Apollo as recompense for stealing his cattle.]]

Western music uses twelve notes called the complete chromatic scale. The seven white keys and their corresponding black keys on a keyboard allows for easy visualization of the complete chromatic scale and the twelve semitones. From this simple twelve note system are all the other scales derived. A scale is simply a way of ordering the twelve sounds found in Western Music. It must be borne in mind that music as an activity precedes musical theory and that the scales we use now have an evolution that predates written records. Today's scale system is referred to as the major-minor system. Go back to the Medieval period and the system used then was called the Church Modes. The study of scales should start with the major scales and minor scales or the blues and pentatonic scales. Unlike the piano where each semitone is represented by a key; on the guitar each semitone is represented by a fret. Pianists visualize the chromatic scale as the seven white keys and five black keys but guitarists should visualize their complete chromatic scale as all the notes from the open E string (low) up to the open high e string. Basically play all the open notes and fretted notes on the first four frets in sequence starting with the low open E string and ending on the high open e string. This is the complete chromatic scale over two octaves as visualized on the guitar. Scales take their names from the first note played - the C major, C minor, C diminished are all scales that start with C. For historical reasons the major scale and the minor scale consists of seven notes. Other scales may use more than seven notes and some (e.g. pentatonic = 5) less than seven notes.

It is important to remember that on the guitar, if you know the pattern of a particular scale, you can move that pattern anywhere else on the fret board and be playing in a different key. By this, I mean if you are playing a major scale, beginning on the low E string at the fifth fret, which is an A note and then you played the same pattern of notes, but you started on the 3rd fret of the low E string, you will be playing a G major scale. If this sounds confusing to you, read the entire article, and if it is still unclear, see the [[w:en:Musical_scale|musical scale]] article on Wikipedia or the [[Music Theory]] wikibook.

There are many different scales: the major scale, three different forms of the minor scale, the blues scale, the pentatonic scale, the whole tone scale, the diminished scale and some scales that originated in Spain and India. There are also very interesting scales from eastern music. It is possible to create your own scales by altering another as you wish, or completely coming up with your own. Note that though there are three minor scales (Natural. Harmonic and Melodic) you don't actually have to learn three different scales. The Harmonic and Melodic Minor scales are variations of the Natural Minor scale. After you have learnt, for example, the A natural minor  scale, you only have to sharpen the seventh note to change it to a Harmonic minor scale. The Melodic Minor has two notes sharpened - the sixth and seventh note. Once again the reasons for the existence of these scales is historical. The Harmonic minor scale is so called because it is from this scale that minor harmony is usually taken. A simpler way of saying this is that the Harmonic minor scale is the scale we use to build the chords in a minor key. The Melodic Minor scale is so called because this scale is frequently used for building melodies.   

The &quot;Circle of Fifths&quot; is a memory aid for learning the major and minor scales which can equally be applied to all scales. The scales in common use have evolved over many centuries and the established major scale, followed by the natural minor and then the two variants: the harmonic minor scale and the melodic minor scale form the basis of Western music. The &quot;Circle of Fifths&quot; and major scales in tab can be found in the Scale Manual section of this book.

All scales in this section are in the key of A and presented in tab except the Hungarian Minor which is given in the key of C. This means that the root note of all these scales is A.

==Pentatonic Scales==

Pentatonic scales are the least complicated, because they have five notes rather than the seven notes used in the major scale. The pentatonic scale is used extensively by blues and rock guitarists and provides an ideal starting point for jamming along with recorded music. A very famous song that uses the A minor pentatonic is &quot;Stairway To Heaven&quot; by Led Zeppelin. 

===A Minor Pentatonic===

    '''A-C-D-E-G-A'''

Most guitarists feel comfortable beginning with the A minor pentatonic, which is the single most popular scale for solos in Western music. Most guitarists know this shape of the Am pentatonic scale by heart, mainly because it is so frequently used in solos. It can also be used for pretty much anything, especially if you want to give it a slightly melancholy sound.

Remember that this scale pattern (and any other scale pattern) can be moved up and down the fretboard therefore allowing the guitarist to play in many different keys using the one shape.

[[Image:Guitar_minor_pentitonic_scale.png|center|600x100]]

In this diagram, the notes are ordered sequentially up the scale (going higher in pitch). The different octaves of the first degree of the scale (in this case, the A note) are highlighted with a yellow dot.

====Learning the Scale====
When you are learning any scale, it is helpful to break it down into smaller chunks, which can be practiced and memorized much more easily. With the A minor pentatonic scale, it is most commonly broken down into these sections. 


Section 1:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |--0-------3--
 B |-----1----3--
 G |--0-----2----
 D |--0-----2----
 A |--0-------3--
 E |--0-------3--
&lt;/div&gt;
[[Image:A minor pentatonic for guitar ex1.png|thumb|800px|none|A minor pentatonic Ex1]]


Section 2:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |-----3-----5--
 B |-----3-----5--
 G |--2--------5--
 D |--2--------5--
 A |-----3-----5--
 E |-----3-----5--
&lt;/div&gt;

[[Image:A minor pentatonic for guitar ex2.png|thumb|800px|none|A minor pentatonic Ex2]]


Section 3:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |--5--------8--
 B |--5--------8--
 G |--5-----7-----
 D |--5-----7-----
 A |--5-----7-----
 E |--5--------8--
&lt;/div&gt;

[[Image:A minor pentatonic for guitar ex3.png|thumb|800px|none|A minor pentatonic Ex3]]


Section 4:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |-----8-----10-
 B |-----8-----10-
 G |--7-----9-----
 D |--7--------10-
 A |--7--------10-
 E |-----8-----10-
&lt;/div&gt;

[[Image:A minor pentatonic for guitar ex4.png|thumb|800px|none|A minor pentatonic Ex4]]


Section 5:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |----10----12--
 B |----10------13
 G |--9-------12--
 D |----10----12--
 A |----10----12--
 E |----10----12--
&lt;/div&gt;

[[Image:A minor pentatonic for guitar ex5.png|thumb|800px|none|A minor pentatonic Ex5]]


Scales should be practiced repeatedly and slowly. Scales are an ideal way to improve hand co-ordination and finger memory which in turn leads to a personal technique. A common technical problem associated with the guitar is string noise. Even a simple chord movement from C to Am should be played at the slowest speed possible with care being taken not to bend the strings and for each note, open or fretted, to ring out clearly. The A minor pentatonic shapes shown above should be played slowly up and down. If you are playing with a plectrum then practice [[Guitar/Alternate Picking|alternate picking]] or [[Guitar/Tremolo Picking|tremolo picking]]. To play scales with fingers just alternate the index and middle finger of the right hand. If you are using a steel-string acoustic then to avoid tendonitis and hand fatigue it is advised that you tune your guitar down a tone when practising scales.

====The Blues scale====
''Please see the [[Guitar/Blues|Blues]] section for more lessons.''

You can easily modify the minor pentatonic scale by adding a single note and turning it into the blues scale - the flatted fifth note (b5) of the scale. In the diagram below, A blues scale is shown at the fifth fret. The number represent the frets played, and the numbers in parentheses represent the Blue Note which, as the name suggests, is the major source of the blues vibe in the scale. The blue note is not actually part of the Minor Pentatonic scale, although it is often added in for extra colour.

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |--5--------8--
 B |--5--------8--
 G |--5-----7-(8)-
 D |--5-----7-----
 A |--5-(6)-7-----
 E |--5--------8--
&lt;/div&gt;

[[Image:A minor pentatonic for guitar inc blue notes.png|thumb|left|800px|A minor pentatonic including &quot;blue&quot; notes]]
{{clear}}

===Major Pentatonic===
The A major pentatonic also has five notes:

'''A-B-C#-E-F#-A'''

[[Image:Guitar_A_major_pentatonic_scale.png|none|600x100]]

The major pentatonic can be formed from any seven note major scale by simply leaving out the fourth and seventh note. The difference between the A minor pentatonic and the A major pentatonic is their modality. They both use the same first degree, however it is the interval between the first degree and the third that defines a scales modality. In the major pentatonic we have a major third (A - C#) so therefore the modal quality of this scale is major. The minor pentatonic has a minor third (A - C) and therefore the modal quality of this scale is minor. Though they both have the same tonality by starting on the same note they differ in sound. Understanding that it is the third of a scale that determines whether a scale is minor mode or major mode is important. In a scale the I, IV and V notes are called the tonal degrees and the III, VI, and VII notes are called the modal degrees. 

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |-----5---------
 B |-----5-----7---
 G |--4-----6------
 D |--4--------7---
 A |--4--------7---
 E |-----5-----7---
&lt;/div&gt;

[[Image:A major pentatonic scale for guitar two octaves 4th position.png|thumb|800px|none|A major pentatonic scale - two octaves]]

Practice this the same way you practice the minor pentatonic scale. When you feel completely comfortable with both pentatonic scales, begin to explore the other different scales.
{{clear}}

==Major Scale==
The pattern for any major scale is 2-2-1-2-2-2-1, meaning that the difference from the first note to the second is 2 frets, from the second to the third is 2 frets, from the third to the fourth is 1 fret, etc. The difference in notes can also be called steps, 2 notes being a whole step, and 1 note being a half step. This pattern in steps can be shown as W-W-H-W-W-W-H or as full tones and semitones T-T-S-T-T-T-S.

Major scale in the key of A

'''A-B-C#-D-E-F#-G#-A''' 

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |-4-5---------
 B |---5---7-----
 G |-4---6-7-----
 D |-4---6-7-----
 A |-4-5---7-----
 E |---5---7-----
&lt;/div&gt;

[[Image:A major scale for guitar two octave 4th position.png|thumb|800px|left|A major scale - two
 octaves]]
{{clear}}

== Three scale concepts at a glance ==

Here all major patterns are shown in comparison to each other in the common 3 scale concepts. We are roughly based on the C major scale.

;Start with the CAGED scales
* Find the square and use it to determine the root note of the major scale.
:[[Image:Scala Carree.svg]]
* Derive the first and second fingerings from this.
* Place the second fingering under the first.
* Connect the lower half of the second fingering to the first fingering using the third fingering.

&lt;div style=&quot;float:left;padding:2px;&quot;&gt;
;first fingerings  
[[Image:Scala 71_2-34_5.svg]]
&lt;/div&gt;
&lt;div style=&quot;float:left;padding:2px;&quot;&gt;
;second fingerings  
[[Image:Scala 6_71-2_34.svg]]
&lt;/div&gt;
&lt;div style=&quot;float:left;padding:2px;&quot;&gt;
;third fingerings
[[Image:Scala 2 34-5 6-71 2.svg]]
&lt;/div&gt;

{{clear}}

* Use it to learn the 5 CAGED scales.
:[[File:Scala Griffbrett ani.gif]]
* Connect the 5 CAGED scales with the slide module.
:[[File:Scala 6 71 2-2 34 5.svg]]
* Note the change in position between the G and B strings.
:[[File:Scala_6_71_2-2_34_5_GB.svg]]
:[[File:Scala Griffbrett moll ani.gif]]
* Familiarize yourself with and engage with the CAGED scales.
:[[File:Crd Grundtonschema ani.gif]]

* Then learn how to easily expand ANY CAGED scale.

:[[Image:Extension of the first and second fingering.svg]]
:
:[[Image:Extension of the third fingering.svg]]

* Learn an alternative third fingering and use it to expand your CAGED scales to the 3 Notes Per Strings scales. (3NPS)

;Alternative third fingering
:[[Image:Scala 5 6 7-1 2 3-4 5 6.svg]]

;Be aware that none of the concepts can be learned and mastered in a weekend. Don't be blinded by false promises on social networks and don't listen to everything that is intended for advanced guitar students.

If you later want to play more demanding polyphonic arrangements (especially jazz, classical and fingerstyle), expand the CAGED and 3NPS scales to the so-called Berklee scales by William Levitt.


;Notes of the C major scale on the fretboard
:[[Image:C-Major-Scale on the fretboard.svg]]
;Intervals of the C major scale (transferable to other keys).
:[[Image:Scala Griffbrett.svg]]
:[[Image:Major-Pattern - 3 Pos Berklee - C-Form CAGED.svg]]
:[[Image:Major-Pattern - 3 Pos 3NPS.svg]]
:[[Image:Major-Pattern - 4 Pos Berklee.svg]]
:[[Image:Major-Pattern - 4 Pos 3NPS.svg]]
:[[Image:Major-Pattern - A-Bb-Form CAGED.svg]]
:[[Image:Major-Pattern - 5 Pos Berklee.svg]]
:[[Image:Major-Pattern - 5 Pos 3NPS.svg]]
:[[Image:Major-Pattern - G-Form CAGED.svg]]
:[[Image:Major-Pattern - G-Form CAGED Var.svg]]
:[[Image:Major-Pattern - 6 Pos Berklee.svg]]
:[[Image:Major-Pattern - 6 Pos 3NPS.svg]]
:[[Image:Major-Pattern - 7 Pos Berklee - E-F-Form CAGED.svg]]
:[[Image:Major-Pattern - 7 Pos 3NPS.svg]]
:[[Image:Major-Pattern - 1 Pos Berklee.svg]]
:[[Image:Major-Pattern - 1 Pos 3NPS.svg]]
:[[Image:Major-Pattern - D-Form CAGED.svg]]
:[[Image:Major-Pattern - 2 Pos Berklee.svg]]
:[[Image:Major-Pattern - 2 Pos 3NPS.svg]]
:[[Image:Major-Pattern - 3 Pos Berklee - C-Form CAGED.svg]]
:[[Image:Longform 1 CAGED.svg]]
:[[Image:Longform 2 CAGED.svg]]
:[[Image:Scala Griffbrett.svg]]
:[[Image:C-Major-Scale on the fretboard.svg]]

Divide each CAGED scale into three pentatonic scales. 

:[[File:Pentatonic Schema Animation.gif]]
:[[File:Scala Griffbrett moll pentatonik ani.gif]]
:[[File:Scala Griffbrett moll pentatonik ani.gif]]

&lt;small&gt;adopted from the German-language Wikibooks. here: [https://de-m-wikibooks-org.translate.goog/wiki/Gitarre:_Die_Major-Patterns?_x_tr_sl=de&amp;_x_tr_tl=en&amp;_x_tr_hl=de&amp;_x_tr_pto=wapp chapter about the major scales] translated from google.&lt;/small&gt;
&lt;!-- Translate it --&gt;

==Natural Minor Scale==
The pattern for any natural minor scale is 2-1-2-2-1-2-2, shown in steps as W-H-W-W-H-W-W

Natural Minor Scale in the key of A

'''A-B-C-D-E-F-G-A'''

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |---5--------
 B |---5-6---8--
 G |-4-5---7----
 D |---5---7----
 A |---5---7-8--
 E |---5---7-8--
&lt;/div&gt;

[[Image:A natural minor scale for guitar two octaves 4th position.png|thumb|800px|none|A natural minor scale - two octaves]]


The movable shape for this scale is shown:
&lt;div style=&quot;line-height:1em&quot;&gt;
 e |-------|---x---|-------|-------|-------|
 B |-------|---x---|---x---|-------|---x---|
 G |---x---|---x---|-------|---x---|-------|
 D |-------|---x---|-------|---x---|-------|
 A |-------|---x---|-------|---x---|---x---|
 E |-------|---x---|-------|---x---|---x---|
              5th
&lt;/div&gt;
{{clear}}

==Harmonic Minor Scale==
The Harmonic minor scale has a very different quality than the minor pentatonic scale. It has a &quot;middle-eastern&quot; sound when used to play lead lines.

'''A-B-C-D-E-F-G#-A'''

This is a moveable shape and to play in other keys just move the shape up or down the neck:

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |--4--5-----7--8--
 B |-----5--6--------
 G |--4--5-----7-----
 D |--------6--7-----
 A |-----5-----7--8--
 E |-----5-----7--8--
&lt;/div&gt;

[[Image:A harmonic minor scale for guitar two octaves 4th position.png|thumb|800px|none|A harmonic minor scale - two octaves]]

This looks a little more complicated, and is certainly more difficult to get to sound nice, but when you have mastered it, it will sound great!
{{clear}}

==Melodic Minor Scale==
This scale is actually ''two'' scales. Thus when one speaks of a &quot;melodic minor&quot; pattern, one refers to two patterns - one ascending and one descending. 

'''A-B-C-D-E-F#-G#-A''' (ascending)
'''A-G-F-E-D-C-B-A'''   (descending)

This is best illustrated by playing the melodic minor scale. Below is the A melodic minor scale in tab; note the sharps when ascending and the naturals when descending.


[[Image:A melodic minor scale for guitar one octave 4th position.png|thumb|800px|none|A melodic minor scale - one octave]]


The ascending pattern is constructed by raising the 6th and 7th steps of the natural minor scale. 
When descending the normal natural minor scale is used without the 6th and 7th raised. The reason for this is to be found in singing. Vocalists find the augmented second between the F and G sharp in the Harmonic minor scale very awkward to sing. It is not impossible but the dissonance of the interval and the sense of &quot;leaping&quot; meant that a different approach was sought. The answer was to also raise the sixth note. The awkward augmented second was gone and the melody flowed better due to the absence of the leap. 

{{clear}}

==Hungarian Minor==
The Hungarian minor scale is a type of combined musical scale. It is akin to the harmonic minor scale, except that it bears a raised fourth. Its tonal center is slightly ambiguous, due to the large number of half steps. Also known as Double Harmonic Minor, or Harmonic Minor #4, it figures prominently in Eastern European music, particularly in gypsy music. Melodies based on this scale have an exotic, romantic flavor.

&lt;div style=&quot;line-height:1em&quot;&gt;
 e |--7--8-----10--11--
 B |--7--8--9----------
 G |--7--8-------------
 D |--------9--10------
 A |--------9--10--11--
 E |-----8-----10--11--
&lt;/div&gt;

[[Image:C hungarian minor scale for guitar one octave 8th position.png|thumb|800px|none|C Hungarian minor scale - one octave]]

A Hungarian minor scale in the key of C would proceed as follows: 

'''C-D-Eb-F#-G-Ab-B-C'''

Its scale degrees are 1 2 b3 #4 5 b6 7 and its step pattern w - h - + - h - h - + - h, where w indicates a whole step, h indicates a half step, and + indicates an augmented second.
{{clear}}
===Derived chords===
Chords that may be derived from the Hungarian minor scale are:

&lt;gallery perrow=6&gt;
File:C minor barre chord for guitar 3rd position.png|'''C Minor'''
File:D7b5 chord for guitar 5th position.png|'''D7 Flat Fifth'''
File:E augmented chord for guitar open position.png|'''E Flat Augmented'''
File:G major chord for guitar open position (no doubled third).png|'''G Major'''
File:A flat seventh chord for guitar barre 4th position.png|'''A Flat Seventh'''
File:B minor sixth chord for guitar open position.png|'''B Minor Sixth'''
&lt;/gallery&gt;


This scale is obtainable from the *Arabic scale by starting from the fourth of that scale. Said another way, the C Hungarian minor scale is equivalent to the G Arabic scale.

In the video game, The Illusion of Gaia (published by the Enix Corporation), the flute melody found in the Inca Ruins uses the C Hungarian minor scale (a #4 is used in the second phrase); this music is also quoted when the player reaches the Larai Cliff stage of the game, transposed to D.

Joe Satriani has composed several songs using the Hungarian minor scale.

==Church Modes==
The Church Modes preceded the Major-Minor system. The student is advised to listen to the music of Palestrina as well as the jazz album ''Kind of Blue'' by Miles Davis; both use modes to great effect. 

For example, in the key of C, the notes are:

'''C-D-E-F-G-A-B-C'''

If you wanted to play in the 2nd mode, called the Dorian mode, then you would just play the same notes, but start on the second note. So instead you would play:

'''D-E-F-G-A-B-C-D'''

The different modes are called:

* Ionian
* Dorian
* Phrygian
* Lydian
* Mixolydian
* Aeolian
* Locrian

The Phrygian mode - '''E F G A B C D E''' - is of special interest to flamenco players. The third and seventh degrees are often sharpened, giving the scale notes '''E F G# A B C D# E'''. This arrangement is commonly used in descending form. The second degree of the scale is referred to as a leaning note, which means the note tends to fall one semitone. In this case F falls to E.

{{Guitar}}

{{BookCat}}</text>
      <sha1>my6sn77ysg7e7weifgtc6vp0gbm1bi6</sha1>
    </revision>
  </page>
  <page>
    <title>German/Level I/Zu Hause essen</title>
    <ns>0</ns>
    <id>74291</id>
    <revision>
      <id>4669765</id>
      <parentid>4669736</parentid>
      <timestamp>2026-09-12T15:34:11Z</timestamp>
      <contributor>
        <username>It-is-Truly-Meet</username>
        <id>3624460</id>
      </contributor>
      <minor />
      <origin>4669765</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="9682" sha1="5o181s59aps6m4ork7z7y4nd8n2dhjr" xml:space="preserve">{|align=&quot;right&quot;
 | __TOC__
|}{{Revise}}
= Lesson I.13: Zu Hause essen =
In this lesson, you'll learn about food in supermarkets, meal preparation, and typical German meals.
== Im Supermarkt ==
===Store Areas and Objects===
{| class=&quot;wikitable&quot; {{German table|Vocabulary|Entrances, Aisles, and Checkout|Eingänge, Gänge und Kassenbereich|0|2}}
!English||German
|-
|supermarket||der Supermarkt
|-
|entrance||der Eingang
|-
|aisle||der Gang
|-
|shelf||das Regal
|-
|checkout/register||die Kasse
|-
|line/queue||die Schlange
|-
|exit||der Ausgang
|-
|opening hours||die Öffnungszeiten
|}
Using these words, you can speed up your grocery trips by going to the ''richtigen Gang''.

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Store Sections|Shop-Bereiche|0|2}}
!English||German
|-
|the bakery section||die Bäckerei
|-
|the butcher counter||die Metzgerei
|-
|the meat counter||die Fleischtheke
|-
|the vegetable section||der Gemüsestand
|-
|the fruit section||die Obsttheke
|-
|the cheese counter||die Käsetheke
|-
|the fish counter||die Fischtheke
|}
Knowing the names of fresh counters helps you navigate efficiently to them. 

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Checkout|Die Kasse|0|2}}
!English||German
|-
|shopping cart||der Einkaufswagen
|-
|shopping basket||der Einkaufskorb
|-
|receipt||die Quittung
|-
|card reader||das Kartenlesegerät
|-
|loose change||das Kleingeld
|-
|to return food||Essen zurückgeben
|}
Knowing these words will help you understand what a cashier is saying.

===Food by Section===
[[File:Eszterhazy-Torte 01.JPG|thumb|right|Esterházy-torte in a Sopron pastry shop.]]
[[File:Nuernberger Lebkuchen 3183857869 0f3f7bcbe3.jpg|thumb|right|Lebkuchen at the Nuremberg Christmas Market]]
{| class=&quot;wikitable&quot; {{German table|Vocabulary|The Backery|Die Bäckerei|0|2}}
!English||German
|-
|bread||das Brot
|-
|sourdough bread||das Sauerteigbrot
|-
|bread roll||das Brötchen
|-
|burger buns||die Burgerbrötchen
|-
|wholemeal||das Vollkorn
|-
|cake||der Kuchen
|-
|pretzel||die Brezel
|-
|croissant||das Croissant
|-
|gingerbread||der Lebkuchen*
|-
|layered cake||die Torte*
|-
|pastries||das Gebäck
|-
|muffin||der Muffin
|-
|cookie/biscuit||der Keks
|-
|icing||die Glasur
|}
&lt;nowiki&gt;*&lt;/nowiki&gt;''Lebkuchen'' are spiced cookies sold during Advent.&lt;br&gt;
&lt;nowiki&gt;*&lt;/nowiki&gt;''Torte'' is a '''layered''' cake with cream or fruit, different from regular ''Kuchen''.

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Fruits|Die Früchte|0|8}}
!English||German||English||German||English||German||English||German
|-
|apple||'''der Apfel'''||dragon fruit||die Drachenfrucht||loquat||die Japanische Wollmispel||pineapple||die Ananas
|-
|apricot||die Aprikose||durian||die Durian||lychee||die Litschi||plum||die Pflaume
|-
|banana||die Banane||fig||die Feige||mandarin||die Mandarine||pomegranate||'''der Granatapfel'''
|-
|blackberry||die Brombeere||gooseberry||die Stachelbeere||mango||die Mango||prickly pear||die Kaktusfeige
|-
|blueberry||die Blaubeere||grape||die Weintraube||mangosteen||die Mangostane||pomelo||die Pomelo
|-
|boysenberry||die Boysenbeere||grapefruit||die Grapefruit||mamoncillo||die Mamoncillo||pulasan||die Pulasan
|-
|Canary melon||die Kanarienmelone||guava||die Guave||minneola||die Minneola||rambutan||die Rambutan
|-
|cantaloupe||die Cantaloupe-Melone||honeydew melon||die Honigmelone||musk melon||die Zuckermelone||raspberry||die Himbeere
|-
|Casaba melon||die Casaba-Melone||horned melon||die Horngurke||nance||die Nance||satsuma||die Satsuma
|-
|Cherimoya||die Cherimoya||jackfruit||die Jackfrucht||nectarine||die Nektarine||soursop||die Stachelannone
|-
|cherry||die Kirsche||jujube||die Jujube||orange||die Orange||star fruit||die Sternfrucht
|-
|Christmas melon||die Weihnachtsmelone||kiwi||'''der Kiwi'''||blood orange||die Blutorange||strawberry||die Erdbeere
|-
|clementine||die Clementine||kumquat||die Kumquat||papaya||die Papaya||tamarillo||die Baumtomate
|-
|cowberry||die Preiselbeere||lemon||die Zitrone||passion fruit||die Passionsfrucht||tangelo||die Tangelo
|-
|Crenshaw melon||die Crenshaw-Melone||lime||die Limette||peach||'''der Pfirsich'''||tangerine||die Mandarine
|-
|currant||die Johannisbeere||loganberry||die Loganbeere||pear||die Birne||ugli fruit||die Ugli-Frucht
|-
|date||die Dattel||longan||die Longan||persimmon||die Kaki||watermelon||die Wassermelone
|}
Observe that ''most'' fruits are feminine and that &quot;''Mandarine''&quot; means both &quot;tangerine&quot; and &quot;mandarin.&quot;

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Vegetables|Die Gemüse|0|8}}
!English||German||English||German||English||German||English||German
|-
|artichoke||die Artischocke||Chard (Red/Swiss)||der Mangold (roter/weißer)||endive lettuce||der Endiviensalat||rhubarb||der Rhabarber
|-
|asparagus||der Spargel
|chicory||die Wegwarte||green/red leaf lettuce||der grüner/roter Blattsalat||Romanesco||der Romanesco
|-
|eggplant||die Aubergine||corn||der Mais||romaine lettuce||der Römersalat||rutabaga||die Steckrübe
|-
|avocado||die Avocado||cress||die Kresse||lima bean||die Limabohne||shallot||die Schalotte
|-
|beet||die Rote Bete||cucumber||die Gurke||mushroom||der Pilz||spinach||der Spinat
|-
|bok choy||der Pak Choi||daikon||der Daikon-Rettich||okra||die Okra||squash||der Kürbis
|-
|broccoli||der Brokkoli||garlic||der Knoblauch||onion||die Zwiebel||acorn squash||der Eichelkürbis
|-
|broccolini||der Brokkolini||green bean||die Grüne Bohne||green onion||die Frühlingszwiebel||butternut squash||der Butternut-Kürbis
|-
|broccoli Raab||der Stängelkohl||greens||das Blattgemüse||parsnip||die Pastinake||pattypan squash||der Patisson-Kürbis
|-
|Brussels sprout||der Rosenkohl||collard greens||der Blattkohl||pea||die Erbse||spaghetti squash||der Spaghettikürbis
|-
|Chinese cabbage||der Chinakohl||mustard greens||die Senfblätter||snap sugar pea||die Zuckererbse||swede||der Schwede
|-
|green cabbage||der Weißkohl||gourd||der Kürbis||snow pea||die Zuckerschote||sweet potato||die Süßkartoffel
|-
|purple cabbage||der Rotkohl||jicama||die Jicama||Anaheim pepper||die Anaheim-Chili||tomatillo||die Tomatillo
|-
|savoy cabbage||der Wirsing||kale||der Grünkohl||sweet pepper||der Paprika||tomato||die Tomate
|-
|carrot||die Karotte||kohlrabi||der Kohlrabi||potato||die Kartoffel||turnip||die Rübe
|-
|cauliflower||der Blumenkohl||leek||der Lauch||pumpkin||der Kürbis||water chestnut||die Wassernuss
|-
|celeriac||die Knollensellerie||arugula lettuce||der Rucola-Salat||radicchio||der Radicchio||yam||die Yamswurzel
|-
|celery||der Sellerie||butter lettuce||der Butterkopfsalat||radish||das Radieschen||zucchini||die Zucchini
|}

[[File:Xanten, Niederrhein, Kuh im Naturschutzgebiet -- 2015 -- Tiere.jpg|thumb|400px|Both raw milk and breastmilk are natural, fresh, and unprocessed milks that contain essential nutrients, fats, proteins, anti-inflammatory enzymes, bioavailable vitamins, and minerals. Raw milk also helps produce lactase in the intestines, allowing many lactose intolerant people to digest it without problems.]]
{| class=&quot;wikitable&quot; {{German table|Vocabulary|Dairy and Eggs|Milchprodukte und Eier|0|2}}
!English||German
|-
|milk||die Milch
|-
|raw milk||die Rohmilch
|-
|certified raw mik||die Vorzugsmilch
|-
|hay milk||die Heumilch
|-
|clarified butter||das Butterschmalz
|-
|cheese||der Käse*
|-
|egg||das Ei
|-
|butter||die Butter
|-
|yogurt||der Joghurt
|-
|cream||die Sahne
|-
|eggnog||der Eierpunsch
|-
|ice cream||das Eis
|}
&lt;nowiki&gt;*&lt;/nowiki&gt;Käse is an irregular noun as it is the only masculine ending in /ə/ that follows the '''strong''' declension.

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Meat and Seafood|Fleisch und Meeresfrüchte|0|2}}
!English||German
|-
|meat||das Fleisch
|-
|chicken||das Hähnchen
|-
|pork||das Schweinefleisch
|-
|beef||das Rindfleisch
|-
|mutton||das Hammelfleisch
|-
|sausage||die Wurst
|-
|fish||der Fisch
|-
|shrimp||die Garnele
|-
|octopus||der Oktopus
|-
|salmon||der Lachs
|-
|bass||der Barsch
|}

===Quantities===
Except the U.S., Myanmar, and Liberia, which use the Imperial System, all nations use the {{w|Metric System}}. Moreover, the euro (€) is the official currency of 21 out of 27 EU countries which together constitute the '''eurozone'''; countries in Europe do '''not''' accept USD in cash.

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Food Containers|Lebensmittelbehälter|0|2}}
!English||German
|-
|bottle||die Flasche
|-
|can/tin||die Dose
|-
|package||die Packung
|-
|slice||die Scheibe
|-
|bag/pouch||der Beutel
|-
|jar/glass||das Glas
|-
|plastic||Kunststoff
|}

{| class=&quot;wikitable&quot; {{German table|Vocabulary|Price Tags|Preisschilder|0|2}}
!English||German
|-
|special offer/sale||das Sonderangebot
|-
|price||der Preis
|-
|deposit on bottles/cans||das Pfand
|-
|value-added tax||die Mehrwertsteuer
|-
|discount||der Rabatt
|}
When buying beverages in returnable containers, factor the ''Pfand'' (a small fee added to beverage containers that you get back when returning them) into your budget.

{{German/Exercise|An der Fleischtheke|'''Übersetzen''' Sie aus dem Deutschen ins Englische:
# Guten Tag. Ich hätte gerne ein halbes Kilo Schinken.
# Gut, das wären 0,34 €.
# Außerdem hätte ich gerne ein Kilo Hühnchen.
# Innenfilet oder Brustfilet?
# Innenfilet, bitte.
# Also, das macht 12,01 € für das Hähnchen. Der Gesamtbetrag liegt bei 12,35 Euro.
# Vielen Dank!
|
# I would like half a kilo of ham.
# Good, that would be €0.34.
# Also, I would like a kilo of chicken.
# Tenderloin or breast fillet?
# Tenderloin, please.
# Alright, that's €12.01 for the chicken. Your total is €12.35.
# Thank you very much!}}

===Polite Shopping Phrases===

&lt;noinclude&gt;{{German/Level I/Footer}}&lt;/noinclude&gt;
{{BookCat}}</text>
      <sha1>5o181s59aps6m4ork7z7y4nd8n2dhjr</sha1>
    </revision>
  </page>
  <page>
    <title>Spanish/Lessons/¿Qué comes?</title>
    <ns>0</ns>
    <id>105612</id>
    <revision>
      <id>4669826</id>
      <parentid>4660990</parentid>
      <timestamp>2026-09-13T06:32:49Z</timestamp>
      <contributor>
        <username>Ziv</username>
        <id>3267536</id>
      </contributor>
      <minor />
      <comment>([[c:GR|GR]])  [[File:Grapes05.jpg]] → [[File:Crimson seedless on the vine.jpg]] [[c:COM:FR#FR2|Criterion 2]] · More precise and not just a meaningless one word name</comment>
      <origin>4669826</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="12224" sha1="gq2e41qwbu6pqp3wznym0dxebbm51vk" xml:space="preserve">[[Image:Alfonso X el Sabio y su corte.jpg|80px|left|Geometría]][[Image:Quijote-2.jpg|right|70px]]
&lt;div style=&quot;margin:0 85px; padding:1ex; background-color:#D5FD87; color:#069; border:1px solid #069; font-size:230%; text-align:center;&quot;&gt;Lesson 6 &amp;mdash; ¿Qué comes?&lt;/div&gt;

[[Image:Aconcagua.jpg|right|200px|thumb|Aconcagua mountain in the Argentinian Andes.]]
__FORCETOC__

[[Image:Jaen Cathedral.jpg|right|200px|thumb|Catedral de Jaén in Spain.]]

== Dialogue ==
{| style=&quot;float:right&quot;
! colspan=2 | Vocabulary
|-
| Necesitar
| To need
|-
| Zumo de
| Juice [of]
|}
: '''''Raúl''''': Hola. ¿Qué compras?
: '''''Sofía''''': Hola, Raúl. Compro una barra de pan y una botella de leche.
: '''''Raúl''''':  Vale. Así, ¿tomas leche y pan tostado para tu desayuno?
: '''''Sofía''''': Sí. Y tú, ¿qué desayunas?
: '''''Raúl''''': Normalmente, tomo zumo de naranja y una manzana.
: '''''Sofía''''': Y ¿tienes la comida que necesitas?
: '''''Raúl''''': Sí. Adiós.
: '''''Sofía''''': ¡Hasta luego!
[[Spanish/Answers/¿Qué comes?#Dialogue|Translation]] (wait until the end of the lesson).

== Food and Drink ==
{| width=100% style=&quot;text-align:center&quot;
| [[Image:French bread DSC00865.JPG|100px|Bread]] || [[Image:Cheese.svg|100px|Cheese]] || [[Image:Freerange eggs.jpg|100px|Egg]] || [[Image:Brown rice.jpg|100px|Rice]] || [[Image:Pasta with pesto.jpg|100px|Pasta]]
|-
| Pan (''m'') || Queso (''m'') || Huevo (''m'') || Arroz (''m'') || Pasta (''f'')
|-
| [[Image:Tomato je.jpg|100px|Tomato]] || [[Image:Kropsla_herfst.jpg|90px|Lettuce]] || [[Image:CDC cuke2.jpg|90px|Cucumber]] || [[Image:Carrot.jpg|100px|Carrot]] || [[Image:Kartoffeln_der_Sorte_Marabel.JPG|100px|Potato]]
|-
| Tomate (''m'') || Lechuga (''f'') || Pepino (''m'') || Zanahoria (''f'') || Patata (''f'')
|-
| [[Image:GreenApple.png|100px|Apple]] || [[Image:Banana.arp.750pix.jpg|100px|Banana]] || [[Image:Orange-fruit-2.jpg|90px|Orange]] || [[Image:PearPhoto.jpg|65px|Pear]] || [[Image:Crimson seedless on the vine.jpg|65px|Grape]]
|- 
| Manzana (''f'') || Plátano (''m'') || Naranja (''f'') || Pera (''f'') || Uva (''f'')
|-
| [[Image:Stilles Mineralwasser.jpg|70px|Water]] || [[Image:Milk glass.jpg|65px|Milk]] || [[Image:Red Wine Glas.jpg|60px|Wine]] || [[Image:A small cup of coffee.JPG|100px|Coffee]] || [[Image:Tea bags.jpg|100px|Tea]]
|-
| Agua (''m'') || Leche (''f'') || Vino (''m'') || Café (''m'') || Té (''m'')
|}

; Notes
* (''m'') above indicates that the noun is masculine (''el queso'' &amp;mdash; &quot;the cheese&quot;; ''los plátanos'' &amp;mdash; &quot;the bananas&quot;), whereas (''f'') above indicates that it is feminine (''la lechuga'' &amp;mdash; &quot;the lettuce&quot;; ''las uvas'' &amp;mdash; &quot;the grapes&quot;)
* In South America, ''papa'' is used instead of ''patata'' and ''Plátano'' refers to a plantain or cooking banana whereas a normal sweet banana is known as a ''banana'' or ''banano''.
* While ''agua'' is feminine, it takes the masculine articles ''un'' and ''el''. For example, ''el agua curiosa'' (&quot;the strange water&quot;) and ''las aguas curiosas'' (&quot;the strange waters&quot;). This is because ''agua'' starts with an accented ''a''.
* ''Con'' means &quot;with&quot;, ''sin'' means without (''café con leche'' means &quot;coffee with milk&quot;, ''café sin leche'' means &quot;coffee without milk&quot;).
* Wine comes in two varieties, &quot;red&quot; and &quot;white&quot;. In Spanish, they are called ''vino tinto'' and ''vino blanco''.

; Examples
* ''Me gustan los huevos.''
*: I like eggs.
* ''No me gusta nada la lechuga.''
*: I don't like lettuce at all.
* ''Me encanta el té con leche.''
*: I love tea with milk
* ''Me gustan mucho las zanahorias, pero los pepinos son aburridos.''
*: I like carrots a lot, but cucumbers are boring.

=== What do you eat? ===
To ask what someone else eats, use ''Qué'' followed by a form of one of the verbs below (''¿Qué comes?'' means &quot;What do you eat?&quot;). To ask what someone likes to eat, use ''Qué te gusta'' then any of the verbs below (''¿Qué te gusta comer?'' means &quot;What do you like to eat?&quot;).

{| {{User:Celestianpower/Spanish table|Verbs|Eating and Drinking|Comer y Beber|2}}
! Español
! Inglés
|-
| Comer
| To eat
|-
| Beber
| To drink
|-
| Tomar
| To have (food/drink)
|-
| Desayunar
| To (eat) breakfast
|-
| Almorzar [in Spain, comer]
| To (eat) lunch
|-
| Cenar
| To dine (eat dinner)
|}

; Note
All of these verbs are regular except ''almorzar'', which is one of the UE Verbs we learnt about in the last chapter; ''almuerzo, almuerzas, almuerza, almorzamos, almorzáis, almuerzan''.

; Examples
* ''¿Qué te gusta almorzar?''
*: What do you like to eat for lunch?
* ''Como naranjas y plátanos, pero no me gustan las peras.''
*: I eat oranges and bananas, but I don't like pears.
* ''Me gusta comer uvas.''
*: I like to eat grapes.
* ''¿Bebes leche?''
*: Do you drink milk?

=== A bottle of wine ===
{| {{User:Celestianpower/Spanish table|Verbs|Eating and Drinking|Comer y Beber|2}}
! Español
! Inglés
|-
| Algo de
| Some
|-
| Un vaso de
| rowspan=2 | A glass of
|-
| Una copa de
|-
| Una botella de
| A bottle of
|-
| Una barra de
| A loaf of
|-
| Un kilo de
| A kilo of
|-
| Un kilo y mediο de
| One and a half kilos of
|-
| Un kilo y cuarto de
| One and a quarter kilos of
|-
| Μedio kilo de
| Half a kilo of
|-
| Un cuarto de kilo de
| A quarter of a kilo of
|}

; Notes
* We previously learnt &quot;unos/unas&quot; as the translation for &quot;some&quot;, e.g. ''unas manzanas'' (&quot;some apples&quot;), but this only works for plural nouns. &quot;Some bread&quot; has to be translated as ''algo de pan'' or just ''pan''.
* Also, there are two ways of saying &quot;a glass of&quot;. ''Copa'' is for glasses with a stem (mostly wine: ''una copa de vino''), and ''vaso'' is used for without a stem.
* Obviously, in all these phrases, the ''un'' can be replaced with any number (''Dos vasos de leche'' means &quot;two glasses of milk&quot;).

; Examples
* ''Tres botellas de vino tinto''
*: Three bottles of red wine
* ''Un medio kilo de arroz''
*: Half a kilo of rice
* ''Una barra de pan''
*: A loaf of bread
* ''Cinco kilos y medio de patatas''
*: Five and a half kilos of potatoes

[[Spanish/Exercises/¿Qué comes?#Food and Drink|Go to the exercises]].

== In the Shop ==
In Spanish, as in English, there are many ways of expressing what you would like to buy, some of which are listed below. You will also see some other useful words and phrases to use when shopping for food.
{| {{User:Celestianpower/Spanish table|Verbs|I would like...|Me gustaría...|2}}
! Español
! Inglés
|-
| Quisiera
| rowspan=3 | I would like
|-
| Querría
|-
| Me gustaría
|-
| Ahí está(n)
| There you go; voila.
|-
| Comprar
| To buy
|-
| La cuenta
| The bill / account
|-
| Cobrar
| To settle in cash
|-
| Costar
| To cost
|-
| Una tienda
| A shop
|}

; Notes
* ''Comprar'' is a regular verb (''compro, compras, compra, compramos, compráis, compran'').
* With ''ahí está(n)'', the ''n'' is added if the noun is plural.
* ''Costar'' is a O =&gt; UE verb (''cuesto, cuestas, cuesta, costamos, costáis, cuestan''), but obviously, you only use the third person.
*: Also, if you want to say &quot;How much does it cost?&quot; you use ''¿Cuánto cuesta(n)?'' (''cuesta'' is for singular things, ''cuestan'' for plurals, as seen below).
* In a bar or café in Spain, one usually pays for everything  on leaving ''¿La cuenta, por favor?'' is to ask for the bill and it relates to the verb ''contar'' - to count or to tell. Alternatively ''cobrar'' (collect) relates to payment (or cash) ''¿me cobra?'' = may I pay?


; Examples
* ''Quisiera una manzana, por favor.''
*: I would like an apple, please.
* ''Querría comprar una barra de pan.''
*: I'd like to buy a loaf of bread.
* ''Me gustaría comprar una botella de vino tinto, por favor.''
*: I'd like to buy a bottle of red wine, please.
* ''¿Cuánto cuestan las uvas?''
*: How much do the grapes cost?
* ''¿Cuánto cuesta un kilo de patatas?''
*: What does a kilo of potatoes cost?

[[Spanish/Exercises/¿Qué comes?#In the shop|Go to the exercises]].

== Adjectives ==
=== &quot;E&quot; and Consonant Adjectives ===
In Spanish, clearly not all adjectives end in &quot;o&quot; or &quot;a&quot;. The good thing about these is that they stay the same, irrespective of gender.
* Adjectives ending in &quot;e&quot; add an &quot;s&quot; when in the plural.
* Adjectives ending in a consonant add an &quot;es&quot; when in the plural.

; Notes
* When an adjective (or indeed a noun) ends in ''z'', it changes to a ''c'' in plural, then adds the &quot;es&quot; (''feliz''/''felices'' &amp;mdash; &quot;happy&quot;).

; Examples
{| width=&quot;50%&quot;
|
* ''El hombre amable''
*: The friendly man
* ''La mujer amable''
*: The friendly woman
* ''Los niños amables''
*: The friendly boys
* ''Las niñas amables''
*: The friendly girls
|
* ''El hombre difícil''
*: The difficult man
* ''La mujer difícil''
*: The difficult woman
* ''Los niños difíciles''
*: The difficult boys
* ''Las niñas difíciles''
*: The difficult girls
|}

=== Colours ===
Colours in Spanish are just adjectives, so they still have to agree and go after the noun. They are shown below.

{| {{User:Celestianpower/Spanish table|Vocabulary|Los colores|The colours|3}}
! Inglés
!
! Español
|-
| Red
|  style=&quot;background:red;{{Text default color}};&quot; bgcolor=red | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Rojo(a)
|-
| Orange
| style=&quot;background:orange;{{Text default color}};&quot; bgcolor=orange | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Naranja / Anaranjado(a)
|-
| Yellow
|  style=&quot;background:yellow;{{Text default color}};&quot; bgcolor=yellow | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Amarillo(a)
|- 
| Green
| style=&quot;background:green;{{Text default color}};&quot; bgcolor=green | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Verde
|-
| Blue
| style=&quot;background:blue;{{Text default color}};&quot; bgcolor=blue | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Azul
|-
| Purple
|  style=&quot;background:purple;{{Text default color}};&quot; bgcolor=purple | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Morado(a) / Violeta
|-
| Brown
|  style=&quot;background:brown;{{Text default color}};&quot; bgcolor=brown | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Marrón / Pardo(a) / Café 
|-
| Pink
|  style=&quot;background:pink;{{Text default color}};&quot; | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Rosa / Rosado(a)
|-
| White
|  style=&quot;background:white;{{Text default color}};&quot; bgcolor=white | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Blanco(a)
|-
| Grey
|  style=&quot;background:gray;{{Text default color}};&quot; bgcolor=gray | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Gris
|-
| Black
|  style=&quot;background:black;color:white;&quot; bgcolor=black | &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;
| Negro(a)
|}

; Notes
* Adjectives can  function as nouns if you add an article in front of them. For example, ''el morado'' means &quot;the purple one&quot;.
* ''Take care with Brown!''
** The plural form of ''marrón'' is ''marrones'' (without the accent);  ''las zanahorias marrones'' means &quot;the brown carrots&quot;.
** Marrones glacés are (in Spanish as in Italian) candied chestnuts.
** Hair and eyes color brown is usually  ''Castaño'' (chesnut).  Brown skin color is ''Moreno'' (tanned).  
* The adjective ''negrita'' (Literally:little black/bold face) is a term of familiarity or endearment is in Spanish and not to be confused with an offensive English expression.
* ''Naranja'' is only the noun form of the word; when used as an adjective, ''anaranjado'' is used.
* The color ''rosa'' ends in &quot;a&quot; even if applied to a masculine noun; ''el balón rosa'', &quot;the pink ball&quot;

; Examples
* ''La manzana verde''
*: The green apple
* ''Los huevos blancos''
*: The white eggs
* ''El queso amarillo''
*: The yellow cheese
* ''Las naranjas anaranjadas''
*: The orange oranges

[[Spanish/Exercises/¿Qué comes?#Adjectives|Go to the exercises]].

== Summary ==
In this lesson, you have learnt
* How to say some foods and drinks (''la lechuga; una manzana; la leche'').
* How to say you eat and drink things (''como, comes, come, comemos, coméis, comen'').
* How to say some simple quantities (''un kilo de patatas; una copa de vino tinto'')
* What to say in a shop (''quisiera; querría; la cuenta'').
* How to form adjectives that don't end in &quot;O&quot; or &quot;A&quot; (''la tienda verde; los quesos azules'')
You should now do the exercise related to each section ([[Spanish/Exercises/¿Qué comes?|found here]]), and translate [[#Dialogue|the dialogue at the top]] before moving on.

You have now completed this chapter! [[Spanish/Contents|Return to the Contents]]...

{{Spanish/Nav}}</text>
      <sha1>gq2e41qwbu6pqp3wznym0dxebbm51vk</sha1>
    </revision>
  </page>
  <page>
    <title>Dutch/Vocabulary/Food</title>
    <ns>0</ns>
    <id>117830</id>
    <revision>
      <id>4669827</id>
      <parentid>4657325</parentid>
      <timestamp>2026-09-13T06:32:50Z</timestamp>
      <contributor>
        <username>Ziv</username>
        <id>3267536</id>
      </contributor>
      <minor />
      <comment>([[c:GR|GR]])  [[File:Grapes05.jpg]] → [[File:Crimson seedless on the vine.jpg]] [[c:COM:FR#FR2|Criterion 2]] · More precise and not just a meaningless one word name</comment>
      <origin>4669827</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3252" sha1="3gi8han0fe6csqknd7iqjf36cttu0kq" xml:space="preserve">Push the arrow button to hear the pronunciation. You might have to increase the volume of you computer or other device, some recordings are rather soft. The recordings only give the noun itself, but remember that you should memorize the article as well, so say: &quot;het brood&quot; and &quot;de pasta&quot; in response to the sound clip.

Hovering over the image will give you the English translation, should you need it.

:The links take you to '''''WikiWoordenboek''''' the Dutch wiktionary. 
:There you can look at any plurals or diminutives. 
:Look under &quot;Afgeleide begrippen&quot; (derived terms) and follow the links. Anything you recognize? (There are usually translations available)
:If necessary use the interwiki link to the English wiktionary for clarification.

The wiktionaries are another way to study a language!

{| width=100% style=&quot;text-align:center&quot;
|[[image:nl-brood.ogg|20px|noicon]][[Image:French bread DSC00865.JPG|100px|Bread]] ||[[image:nl-kaas.ogg|20px|noicon]][[Image:Cheese.svg|100px|Cheese]] ||[[image:nl-ei.ogg|20px|noicon]] [[Image:Freerange eggs.jpg|100px|Egg]] || [[image:nl-rijst.ogg|20px|noicon]][[Image:Brown rice.jpg|100px|Rice]] || [[image:nl-pasta.ogg|20px|noicon]][[Image:Pasta with pesto.jpg|100px|Pasta]]
|-
| het [[:nl:wikt:brood|brood]] || de [[:nl:wikt:kaas|kaas]] (m./v.) || het [[:nl:wikt:ei|ei]] || de [[:nl:wikt:rijst|rijst]] (m.) || de [[:nl:wikt:meelspijs|meelspijs]] (v.) &lt;br&gt; de [[:nl:wikt:pasta|pasta]] (m./v.)
|-
|[[image:nl-brood.ogg|20px|noicon]] [[Image:Tomato je.jpg|100px|Tomato]] ||[[image:nl-sla.ogg|20px|noicon]] [[Image:Kropsla_herfst.jpg|90px|Lettuce]] || [[image:nl-komkommer.ogg|20px|noicon]][[Image:CDC cuke2.jpg|90px|Cucumber]] || [[image:nl-peen.ogg|20px|noicon]][[Image:Carrot.jpg|100px|Carrot]] || [[image:nl-aardappel.ogg|20px|noicon]][[Image:Kartoffeln_der_Sorte_Marabel.JPG|100px|Potato]]
|-
| de [[:nl:wikt:tomaat|tomaat]] (v.) || de [[:nl:wikt:sla|sla]] (v.) || de [[:nl:wikt:komkommer|komkommer]] (m.) || de [[:nl:wikt:wortel|wortel]] (m.), de [[:nl:wikt:peen|peen]] (v.) || de [[:nl:wikt:aardappel|aardappel]] (m.)
|-
|[[image:nl-appel.ogg|20px|noicon]] [[Image:GreenApple.png|100px|Apple]] || [[image:nl-banaan.ogg|20px|noicon]][[Image:Banana.arp.750pix.jpg|100px|Banana]] || [[image:nl-sinaasappel.ogg|20px|noicon]][[Image:Orange-fruit-2.jpg|90px|Orange]] || [[image:nl-peer.ogg|20px|noicon]][[Image:PearPhoto.jpg|65px|Pear]] || [[image:nl-druiven.ogg|20px|noicon]][[Image:Crimson seedless on the vine.jpg|65px|Grape]]
|- 
|de [[:nl:wikt:appel|appel]] (m.) || de [[:nl:wikt:banaan|banaan]] (v./m.) || de [[:nl:wikt:sinaasappel|sinaasappel]] (m.) || de [[:nl:wikt:peer|peer]] (v.) || de [[:nl:wikt:druif|druiven]] (v.)
|-
|[[image:nl-water.ogg|20px|noicon]] [[Image:Stilles Mineralwasser.jpg|70px|Water]] || [[image:nl-melk.ogg|20px|noicon]][[Image:Milk glass.jpg|65px|Milk]] || [[image:nl-wijn.ogg|20px|noicon]][[Image:Red Wine Glas.jpg|60px|Wine]] || [[image:nl-koffie.ogg|20px|noicon]][[Image:A small cup of coffee.JPG|100px|Coffee]] || [[image:nl-thee.ogg|20px|noicon]][[Image:Tea bags.jpg|100px|Tea]]
|-
| het [[:nl:wikt:water|water]] || de [[:nl:wikt:melk|melk]] (v.) || de [[:nl:wikt:wijn|wijn]] (m.) || de [[:nl:wikt:koffie|koffie]] (m.) || de [[:nl:wikt:thee|thee]] (v.)
|}

{{BookCat}}</text>
      <sha1>3gi8han0fe6csqknd7iqjf36cttu0kq</sha1>
    </revision>
  </page>
  <page>
    <title>Wikijunior:Human Body/Authors</title>
    <ns>110</ns>
    <id>118493</id>
    <revision>
      <id>4669766</id>
      <parentid>4079403</parentid>
      <timestamp>2026-09-12T16:28:30Z</timestamp>
      <contributor>
        <username>Hafsaasad2016</username>
        <id>3625794</id>
      </contributor>
      <comment>/* Authors */</comment>
      <origin>4669766</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="344" sha1="f4wgvro1s5lwkrvyliqtjpic9xqq4m3" xml:space="preserve">=Authors=
*[[Shampa.Ghosh|Shampa.Ghosh]] - '''Shampa Ghosh''', ''Ph.D.'', India
*[[Basejumper123|Basejumper123]] - Benjamin Mitchell, USA
*[[Alicia Winifred|Alicia Winifred]] -  ''started Wikijunior Human Body/Medical - Laparoscopic Surgery ''
* Karen Fasimpaur
* Aayush Mudgal [ Director ] A.M. Creation
*Shefa Tabassum
{{BookCat}}
*Hafsa Asad</text>
      <sha1>f4wgvro1s5lwkrvyliqtjpic9xqq4m3</sha1>
    </revision>
    <revision>
      <id>4669767</id>
      <parentid>4669766</parentid>
      <timestamp>2026-09-12T16:30:21Z</timestamp>
      <contributor>
        <username>Hafsaasad2016</username>
        <id>3625794</id>
      </contributor>
      <comment>/* Authors */</comment>
      <origin>4669767</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="332" sha1="3quwabz6a5n8gqma1ntt3imbetqkp0b" xml:space="preserve">=Authors=
*[[Shampa.Ghosh|Shampa.Ghosh]] - '''Shampa Ghosh''', ''Ph.D.'', India
*[[Basejumper123|Basejumper123]] - Benjamin Mitchell, USA
*[[Alicia Winifred|Alicia Winifred]] -  ''started Wikijunior Human Body/Medical - Laparoscopic Surgery ''
* Karen Fasimpaur
* Aayush Mudgal [ Director ] A.M. Creation
*Shefa Tabassum
{{BookCat}}</text>
      <sha1>3quwabz6a5n8gqma1ntt3imbetqkp0b</sha1>
    </revision>
  </page>
  <page>
    <title>Horticulture/Vitis</title>
    <ns>0</ns>
    <id>119168</id>
    <revision>
      <id>4669828</id>
      <parentid>3354405</parentid>
      <timestamp>2026-09-13T06:32:51Z</timestamp>
      <contributor>
        <username>Ziv</username>
        <id>3267536</id>
      </contributor>
      <minor />
      <comment>([[c:GR|GR]])  [[File:Grapes05.jpg]] → [[File:Crimson seedless on the vine.jpg]] [[c:COM:FR#FR2|Criterion 2]] · More precise and not just a meaningless one word name</comment>
      <origin>4669828</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="8545" sha1="nsqfsbgukw87ap342kx9vduyo90tns4" xml:space="preserve">{{Hortibox|Grapes
| Image  = Close up grapes.jpg
| Binomial  = 
| Genus = Vitis
| Family = Vitaceae
| Variety  = 
| Type  = Vines
| Sun  = 
| Water  = 
| Soil  = 
| USDA Hardiness Zone  = 
| Sunset Zone  = 
| Propagation  = 
| Pruning season  = 
| Pruning tolerance  = 
| Forcing  = 
| Transplant  = 
| Pest issues  = 
| Disease issues  = 
| Bloom season  = 
| Fruit season  = 
| Sowing methods  = 
| Harvest  = 
| Storage  = 
| Weediness  = All species can be agressive
| Pollination = Insects
| Seed Dispersal =
| Germination Time =
| Germination Signal =
| Ripe Seed =
| Seed Banking =
| Vegetative Spread =
| Allelopathy =
| Group =
| Sowing time =
| Days to germination =
| Days to baby =
| Days to maturity =
| Bolting =
| Flat cropping =
| Planting depth =
| Plant spacing =
| Row spacing =
| Seed collection =
| Height and spread =
| Root =
| Growth rate =
| Shade cast =
| Underplanting =
| Toxicity and edibility = Fruits and leaves are edible
}}
A '''grape''' is the fruit that grows on the woody vines of the family [[../Vitaceae/]]. Grapes grow in clusters of 6 to 300, and can be black, blue, golden, green, purple, red, pink, brown, peach or white. 

==Description==
Plants in this genus are woody vines which climb using tendrils. The alternate leaves are simple, palmately veined and often lobes. Flowers are produced in clusters of 6-300. The fruits are berries with 1-6 hard seeds.

==Growing conditions==
&lt;!--sun, soil, etc.--&gt;

==Species==
Many species of grapevines exist, including:

*''[[../Vitis vinifera/]]'', the European winemaking grapevine. Native to virtually all of mainland Europe.
*''[[../Vitis labrusca/]]'', the North American table and grape juice grapevines, sometimes used for wine. Native to the Eastern U.S. and Canada.
*''[[../Vitis riparia/]]'', a wild vine of North America, sometimes used for winemaking and for jam. Native to the entire Eastern U.S. and north to Quebec.
*''[[../Vitis rotundifolia/]]'', the muscadines, used for jams  and wine. Native to the Southeastern U.S. from Delaware to the Gulf of Mexico.
*''[[../Vitis aestivalis/]]'', the variety Norton (AKA Cynthiana) is used for winemaking
*''[[../Vitis lincecumii/]]'' (also called ''Vitis aestivalis'' or ''Vitis lincecumii''), ''[[../Vitis berlandieri/]]'' (also called ''Vitis cinerea'' var. helleri), ''[[../Vitis cinerea/]]'', ''[[../Vitis rupestris/]]'' are used for making hybrid grapevines and for pest-resistant rootstocks.
*''[[../Vitis arizonica/]]'' A desert grapevine found in the southwestern US that is hardy against extremes of temperature. Can be used for wines.
*''[[../Vitis californica/]]'' A grapevine important to the California wine industry for its rootstock which is able to withstand pests and cooler weather. Native to California and Oregon.
*''[[../Vitis vulpina/]]''  Frost grape. Native to the Midwest east to the coast up through New York. 

There are many [[w:List of grape varieties|varieties]] of grapevines; most are cultivars of ''V. vinifera''.

Hybrid grapes also exist, and these are primarily crosses between ''[[../Vitis vinifera/]]'' and one or more varieties of ''[[../Vitis labrusca/]]'', ''[[../Vitis riparia/|../Vitis riparia/]]'' or ''[[../Vitis aestivalis/]]''. Hybrids tend to be less susceptible to frost and disease (notably phylloxera), but wine from some hybrids may have a little of the characteristic &quot;foxy&quot; odor of ''[[../Vitis labrusca/]]''.

==Uses==
They can be eaten raw or used for making jam, grape juice, jelly, wine and grape seed oil. Cultivation of grapevines occurs in vineyards, and is calleviticulture. One who studies and practices growing grapes for wine is called a viticulturalist.

Raisins are the dried fruit of the grapevine, and the name actually comes from the French word for &quot;grape&quot;. Wild grapevines are often considered a nuisance weed, as they cover other plants with their usually rather aggressive growth.

The leaves of the grape vine itself are considered edible and are used in the production of dolmades.

==Maintenance==
The most important maintenance requirement for grapes is regular pruning. Vines should be pruned back to spurs while dormant, in order to ensure good air circulation and keep the plants from getting out of hand. 

Adequate calcium should be maintained in the soil if growing for fruit.

==Propagation==
Cultivars are almost always grafted.

==Harvesting==
&lt;!--Discuss harvesting and storage--&gt;

==Pests and diseases==
'''Scorch, Wilt, Dieback'''
*Xylella fastidiosa (Pierce’s Disease)
'''[[../Powdery Mildews/]]'''

'''[[../Downy Mildews/]]'''

'''[[../Diebacks/]]'''
*Eutypa lata
*Eutypa armeniacae
'''[[../Bunch Rots/]]'''
*Aspergillus niger
*''[[../Botrytis cinerea/]]''
*Lasoidiplodia theobromae
'''[[../White Molds/]]'''
*''[[../Sclerotinia/]]''
'''[[../Aphids/]]'''
*Grape Phylloxeran: ''[[../Daktulosphaira vitifoliae/]]''
'''[[../Scales/]]'''
*Calico Scale: ''[[../Eulecanium cerasorum/]]''
*European Fruit Lecanium Scale: ''[[../Lecanium corni/]]''
*Oystershell Scale: ''[[../Lepidosaphes ulmi/]]''
*Cottony Grape Scale: ''[[../Pulvinaria vitis/]]''
*European Peach Scale: ''[[../Parthenolecanium persicae/]]''
'''[[../Hoppers/]]'''
*Eastern Grape Leafhopper: ''[[../Erythroneura comes/]]''
*Threebanded Leafhopper: ''[[../Erythroneura tricincta/]]''
*Variegated Leafhopper: ''[[../Erythroneura variabilis/]]''
*Virginiacreeper Leafhopper: ''[[../Erythroneura ziczac/]]''
*Western Grape Leafhopper: ''[[../Erythroneura vulnerata/]]''
'''[[../Mealybugs/]]'''
*Grape Mealybug: ''[[../Pseudococcus maritimus/]]''
*Obscure Mealybug: ''[[../Psudococcus viburni/]]''
'''[[../Bugs/]]'''
*Campylomma Bug: ''[[../Campylomma verbasci/]]''
'''[[../Flies/]]'''
*Grape Tumid Gallmaker: ''[[../Janetiella breviconda/]]''
*Grape Gall Midges: ''[[../Schizomyia/]]''
'''[[../Beetles/]]'''
*Grape Cane Girdler: ''[[../Ampeloglypter ater/]]''
*Grape Cane Gallmaker: ''[[../Ampeloglypter sesostris/]]''
*Rose Chafer: ''[[../Macrodactylus subspinosus/]]''
*Japanese Beetle: ''[[../Popillia japonica/]]''
*Apple Flea Beetle: ''[[../Altica foliacea/]]''
*Apple Twig Borer: ''[[../Amphicerus bicaudatus/]]''
*Grape Flea Beetle: ''[[../Altica chalybea/]]''
*Grape Curculio: ''[[../Craponius inaequalis/]]''
'''[[../Caterpillars/]]'''
*Grapeleaf Skeletonizer: ''[[../Harrisina americana/]]''
*Achemon Sphinx: ''[[../Eumorpha achemon/]]''
*Eightspotter Forester: ''[[../Alypia octomaculata/]]''
*Grape Berry Moth: ''[[../Endopiza viteana/]]''
*Grapevine Root Borer: ''[[../Vitacea polistiformis/]]''
*Redbanded Leafroller: ''[[../Argyotaenia velutinana/]]''
*Spotted Cutworms: ''[[../Xestia/]]'' spp.
*Virginiacreeper Sphinx: ''[[../Darapsa myron/]]''
*Western Grapeleaf Skeletonizer: ''[[../Harrisia brillans/]]''
*Whitelined Sphinx: ''[[../Hyles lineata/]]''
'''[[../Sawflies/]]'''
*Grape Sawfly: ''[[../Erythraspides vitis/]]''
'''[[../Wasps/]]'''
*Yellowjackets
'''[[../Bees/]]'''
*Leafcutter Bees
'''[[../Mites/]]'''
*Grape Erineum Mite: ''[[../Colomerus vitis/]]''
*European Red Mite: ''[[../Panonychus ulmi/]]''

==Gallery==
&lt;gallery&gt;
Image:Grape 00005.jpg
Image:Crimson seedless on the vine.jpg|A bunch of grapes
Image:Autumn Royal grapes.jpg|Autumn Royal grapes
Image:Ripe grapes.jpg|Red and green grapes
Image:More grapes.jpg|Red grapes
Image:Flame seedless grapes.jpg|Flame seedless grapes
Image:Concord grape plant.jpg|Foliage of the Concord grape plant
Image:Young grapes.jpg|Young grapes
|Pinot Noir grapes
Image:Wine grapes baja.jpg|Guadalupe Valley Vineyards, Ensenada, Baja California, Mexico / '''''Viñedos del Valle de Guadalupe, Ensenada, Baja California, México'''''
Image:Uvas.jpg|Guadalupe Valley Vineyards, Ensenada, Baja California, Mexico / '''''Viñedos del Valle de Guadalupe, Ensenada, Baja California, México'''''
Image:Geneva Grapevine.JPG|A vineyard in the Canton of Geneva.
&lt;/gallery&gt;

==References==
{{commons|{{SUBPAGENAME}}}}
*{{cite book |last=Cranshaw |first=Whitney | authorlink= |coauthors= |editor= |others= |title=Garden Insects of North America: The Ultimate Guide to Backyard Bugs|edition= |year=2004 |publisher=Princeton University Press |pages=625-626 }}
*{{cite book |last= Pippa Greenwood, Andrew Halstead, A.R. Chase, Daniel Gilrein|first= | authorlink= |coauthors= |editor= |others= |title=American Horticultural Society Pests &amp; Diseases: The Complete Guide to Preventing, Identifying, and Treating Plant Problems |edition= First Edition|year=2000 |publisher= Dorling Kindersley (DK) Publishing, inc.|pages=204 }}
&lt;references/&gt;

[[{{BOOKCATEGORY}}/Finder/Taxonomy/Genera|{{SUBPAGENAME}}]]</text>
      <sha1>nsqfsbgukw87ap342kx9vduyo90tns4</sha1>
    </revision>
  </page>
  <page>
    <title>Git/Submodules and Superprojects</title>
    <ns>0</ns>
    <id>137418</id>
    <revision>
      <id>4669821</id>
      <parentid>4657259</parentid>
      <timestamp>2026-09-13T06:27:50Z</timestamp>
      <contributor>
        <username>JackPotte</username>
        <id>99248</id>
      </contributor>
      <minor />
      <comment>[[WB:REVERT|Reverted]] edit by [[Special:Contributions/~2026-44254-82|~2026-44254-82]] ([[User talk:~2026-44254-82|talk]]) to last version by ~2026-43765-42</comment>
      <origin>4656733</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="2654" sha1="j6zef9qotogcxcwxh6llru516j7ed0u" xml:space="preserve">&lt;gallery&gt;
&lt;gallery&gt;
Example.jpg|Caption1
Example.jpg|Caption2
&lt;/gallery&gt;
&lt;gallery&gt;
Example.jpg|Caption1
Example.jpg|Caption2
&lt;/gallery&gt;
&lt;/gallery&gt;
A '''superproject''' is a new aspect of git which has been in development for a long while. It addresses the need for better control over numerous git repositories. The porcelain for the superproject functionality is fairly new and was only recently released with Git v1.5.3.

A Git '''project''' may consist of a set of ''git repositories'' and each of these &quot;git repositories&quot; is called a '''module'''.You can think of a '''module''' as a '''project,''' and the '''project''' as a '''module.''' It really doesn't make too much sense why either of these terms would have a ''sub-'' or ''super-'' prefix without their alternative; nonetheless, that's how the official Git documentation will refer to them.

The only git application specific to the submodule/superproject functionality is '''git-module'''.

== Superprojects ==
A '''Superproject''', is simply a git repository. To create a superproject, simply ''git init'' any directory, and ''git submodule add'' all of the git archives you wish to include. A quick aside, you can not currently ''git submodule add'' git repositories that are direct children within the same directory.{{ref|lie_parent}}

The resulting structure will look similar to this:
 |- superproject
   |- submodule (git archive) [a]
   |- submodule [b]
   |- submodule [c]
   |- submodule [d]

When someone pulls down the superproject, they will see a series of empty folders for each submodule. They can then ''git submodule init'' all of those that they wish to utilize.

== Submodules ==
A ''git archive'' is said to become a ''submodule'' the second after you execute ''git submodule add'' in another git repository.


&lt;!--
&lt;syntaxhighlight lang=&quot;bash&quot;&gt;
atomic-example
&lt;/syntaxhighlight&gt;
--&gt;

== Work Flow ==

The work flow of superprojects, and submodules should generally adhere to the following:
# the repo has been initialized in path_to_working_directory
# Make change in submodule
# ''git commit'' change in submodule
# ''git commit'' change in superproject
# ''git submodule update'' to push change to the individual repositories that predate the superproject.

==Footnotes==
#{{note|lie_parent}} Well that isn't true at all, Git supports this as of v1.5.3, but the official porcelain doesn't. You can ''git init'' a parent directory, and create your own &quot;.gitmodules&quot;, then follow it up with a ''git submodule init''. Generally speaking though, what the porcelain doesn't cover is outside of the scope of this book.

{{BookCat}}

[[fr:Git/Sous-modules et Super-projets]]</text>
      <sha1>j6zef9qotogcxcwxh6llru516j7ed0u</sha1>
    </revision>
    <revision>
      <id>4669823</id>
      <parentid>4669821</parentid>
      <timestamp>2026-09-13T06:28:13Z</timestamp>
      <contributor>
        <username>JackPotte</username>
        <id>99248</id>
      </contributor>
      <comment>Undid 6 revisions from [[Special:Diff/4640901|4640901]] until [[Special:Diff/4669821|4669821]]</comment>
      <origin>4669823</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="2507" sha1="36w2bm8w7dxmp1l6bt052rj062150p8" xml:space="preserve">A '''superproject''' is a new aspect of git which has been in development for a long while. It addresses the need for better control over numerous git repositories. The porcelain for the superproject functionality is fairly new and was only recently released with Git v1.5.3.

A Git '''project''' may consist of a set of ''git repositories'' and each of these &quot;git repositories&quot; is called a '''module'''.You can think of a '''module''' as a '''project,''' and the '''project''' as a '''module.''' It really doesn't make too much sense why either of these terms would have a ''sub-'' or ''super-'' prefix without their alternative; nonetheless, that's how the official Git documentation will refer to them.

The only git application specific to the submodule/superproject functionality is '''git-module'''.

== Superprojects ==
A '''Superproject''', is simply a git repository. To create a superproject, simply ''git init'' any directory, and ''git submodule add'' all of the git archives you wish to include. A quick aside, you can not currently ''git submodule add'' git repositories that are direct children within the same directory.{{ref|lie_parent}}

The resulting structure will look similar to this:
 |- superproject
   |- submodule (git archive) [a]
   |- submodule [b]
   |- submodule [c]
   |- submodule [d]

When someone pulls down the superproject, they will see a series of empty folders for each submodule. They can then ''git submodule init'' all of those that they wish to utilize.

== Submodules ==
A ''git archive'' is said to become a ''submodule'' the second after you execute ''git submodule add'' in another git repository.


&lt;!--
&lt;syntaxhighlight lang=&quot;bash&quot;&gt;
atomic-example
&lt;/syntaxhighlight&gt;
--&gt;

== Work Flow ==

The work flow of superprojects, and submodules should generally adhere to the following:
# the repo has been initialized in path_to_working_directory
# Make change in submodule
# ''git commit'' change in submodule
# ''git commit'' change in superproject
# ''git submodule update'' to push change to the individual repositories that predate the superproject.

==Footnotes==
#{{note|lie_parent}} Well that isn't true at all, Git supports this as of v1.5.3, but the official porcelain doesn't. You can ''git init'' a parent directory, and create your own &quot;.gitmodules&quot;, then follow it up with a ''git submodule init''. Generally speaking though, what the porcelain doesn't cover is outside of the scope of this book.

{{BookCat}}

[[fr:Git/Sous-modules et Super-projets]]</text>
      <sha1>36w2bm8w7dxmp1l6bt052rj062150p8</sha1>
    </revision>
  </page>
  <page>
    <title>Wikibooks:Reading room/Administrative Assistance</title>
    <ns>4</ns>
    <id>140081</id>
    <revision>
      <id>4669806</id>
      <parentid>4669646</parentid>
      <timestamp>2026-09-13T04:08:48Z</timestamp>
      <contributor>
        <username>MathXplore</username>
        <id>3097823</id>
      </contributor>
      <comment>Reporting ~2026-49632-08</comment>
      <origin>4669806</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="15673" sha1="46n0x5cf5mpjagnuzgoo979j7jvgabx" xml:space="preserve">__NEWSECTIONLINK__ {{Discussion Rooms}} {{shortcut|WB:AN|WB:AA}} {{TOC left}}
{{User:MiszaBot/config
|archive = Wikibooks:Reading room/Administrative Assistance/Archives/%(year)d/%(monthname)s
|algo = old(14d)
|counter = 1
|minthreadstoarchive = 1
|minthreadsleft = 1
}}
{{ombox|type=content|text='''To request a rename or usurpation''', go to the global request page at Meta [[meta:SRUC|here]].&lt;br /&gt;''Please do not post those requests here!''}}
{{Clear}}
Welcome to the '''Administrative Assistance reading room'''.  You can request assistance from [[WB:ADMIN|administrators]] for handling a variety of problems here and alert them about problems which may require special actions not normally used during regular content editing. Please be patient as administrators are often quite busy with either their own projects or trying to perform general maintenance and cleanup.

You can deal with most vandalism yourself: [[Wikibooks:Dealing with vandalism|fix it]], then [[Wikibooks:Templates/User_notices|warn the user]]. If there is repeated vandalism by one user, lots of vandalism on a single page, or vandalism from many users, tell an admin here, or in [irc://irc.freenode.net/wikibooks #wikibooks] (say &lt;code&gt;!admin&lt;/code&gt; to get attention).

For more general questions and assistance that doesn't require an administrator, please use the [[WB:HELP|Assistance Reading Room]].
{{clear}}

[[Category:Reading room]]

== Gloriagulshan reported by MathXplore ==

* {{userlinks|Gloriagulshan}}

[[:w:Wikipedia:Sockpuppet investigations/Kagoz]] ([[Special:Contributions/Tikapara]], [[Wikibooks:Reading_room/Administrative_Assistance/Archives/2025/September#Tikapara_reported_by_MathXplore]]), created page [[Introduction to Filmmaking]] Contributed by Ali Zulfikar Zahedi ([[:w:Ali Zulfikar Zahedi]], [[:w:simple:Ali Zulfikar Zahedi]]) &lt;!-- USERREPORTED:/Gloriagulshan/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 03:56, 29 August 2026 (UTC)

:I believe this page is intended as instructional material for learning filmmaking rather than as an encyclopedic article. I will revise the page to focus on practical filmmaking concepts, methods, and processes in accordance with the purpose of Wikibooks. [[User:Gloriagulshan|Gloriagulshan]] ([[User talk:Gloriagulshan|discuss]] • [[Special:Contributions/Gloriagulshan|contribs]]) 04:20, 29 August 2026 (UTC)
: Cc: {{ping|SHB2000|MarcGarver}} [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:41, 29 August 2026 (UTC)
::I see the account is glocked, and there are no sleepers that aren't already locked, so nothing more to do. [[User:MarcGarver|MarcGarver]] ([[User talk:MarcGarver|discuss]] • [[Special:Contributions/MarcGarver|contribs]]) 11:18, 3 September 2026 (UTC)

== Atlanticgym reported by MathXplore ==

* {{userlinks|Atlanticgym}}

Link spam, [[Special:AbuseLog/315249]] &lt;!-- USERREPORTED:/Atlanticgym/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:32, 29 August 2026 (UTC)

:{{done}} --[[User:SHB2000|SHB2000]] ([[User talk:SHB2000|discuss]] • [[Special:Contributions/SHB2000|contribs]]) 12:35, 29 August 2026 (UTC)
== Makowe2026 reported by Veritas Sapientiae ==

* {{userlinks|Makowe2026}}

Spam &lt;!-- USERREPORTED:/Makowe2026/ --&gt; [[User:Veritas Sapientiae|Veritas Sapientiae]] ([[User talk:Veritas Sapientiae|discuss]] • [[Special:Contributions/Veritas Sapientiae|contribs]]) 13:53, 29 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 19:20, 29 August 2026 (UTC)
== Abir077 reported by MathXplore ==

* {{userlinks|Abir077}}

Link spam, [[Special:AbuseLog/315272]] &lt;!-- USERREPORTED:/Abir077/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:07, 31 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:46, 31 August 2026 (UTC)
== Jeevandan26 reported by MathXplore ==

* {{userlinks|Jeevandan26}}
Link spam, [[Special:AbuseLog/315288]] &lt;!-- USERREPORTED:/Jeevandan26/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:14, 1 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 1 September 2026 (UTC)
== Mohansai00116 reported by MathXplore ==

* {{userlinks|Mohansai00116}}

Link spam, [[Special:AbuseLog/315335]] &lt;!-- USERREPORTED:/Mohansai00116/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:09, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:04, 3 September 2026 (UTC)

== Fatemai6 reported by MathXplore ==

* {{userlinks|Fatemai6}}

Link spam, [[Special:AbuseLog/315329]] &lt;!-- USERREPORTED:/Fatemai6/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:10, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan147 reported by MathXplore ==

* {{userlinks|Kamrulhasan147}}

Link spam, [[Special:AbuseLog/315327]], [[Special:Contributions/Kamrulhasan142]] &lt;!-- USERREPORTED:/Kamrulhasan147/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:12, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan142 reported by MathXplore ==

* {{userlinks|Kamrulhasan142}}

Link spam, [[Special:AbuseLog/315295]], [[Special:Contributions/Kamrulhasan147]] &lt;!-- USERREPORTED:/Kamrulhasan142/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:13, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Twenty7incgs reported by MathXplore ==

* {{userlinks|Twenty7incgs}}

Link spam, [[Special:AbuseLog/315323]] &lt;!-- USERREPORTED:/Twenty7incgs/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:14, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Tailleash reported by MathXplore ==

* {{userlinks|Tailleash}}

Link spam, [[Special:AbuseLog/315318]] &lt;!-- USERREPORTED:/Tailleash/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:15, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Md Akash Mia12 reported by MathXplore ==

* {{userlinks|Md Akash Mia12}}

Link spam, [[Special:AbuseLog/315299]], [[Special:AbuseLog/315298]] &lt;!-- USERREPORTED:/Md Akash Mia12/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:17, 2 September 2026 (UTC)
: {{done|Page deleted}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:03, 3 September 2026 (UTC)

== Vapesitefiftybar reported by MathXplore ==

* {{userlinks|Vapesitefiftybar}}

Link spam, [[Special:AbuseLog/315338]] &lt;!-- USERREPORTED:/Vapesitefiftybar/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:40, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)
== Myteethtime1 reported by MathXplore ==

* {{userlinks|Myteethtime1}}

Spam &lt;!-- USERREPORTED:/Myteethtime1/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:54, 4 September 2026 (UTC)
: {{Done}} by MarcGarver. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)

== Rajstartupservices reported by MathXplore ==

* {{userlinks|Rajstartupservices}}

Link spam, [[Special:AbuseLog/315363]] &lt;!-- USERREPORTED:/Rajstartupservices/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 14:33, 4 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)
== Reazulkarim545456 reported by MathXplore ==

* {{userlinks|Reazulkarim545456}}

Link spam, [[Special:AbuseLog/315377]] &lt;!-- USERREPORTED:/Reazulkarim545456/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:39, 6 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:19, 6 September 2026 (UTC)

== Fahmidafy reported by MathXplore ==

* {{userlinks|Fahmidafy}}

Link spam, [[Special:AbuseLog/315378]] &lt;!-- USERREPORTED:/Fahmidafy/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:40, 6 September 2026 (UTC)
: The filter stopped them three times, no action taken. Please re-report if they continue spamming. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 6 September 2026 (UTC)

== Grow spark digital reported by MathXplore ==

* {{userlinks|Grow spark digital}}

Link spam, [[Special:AbuseLog/315381]] &lt;!-- USERREPORTED:/Grow spark digital/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:42, 6 September 2026 (UTC)
: Only one filter hit, seems stale. Please re-report if they continue to spam. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:49, 6 September 2026 (UTC)

== Korigosnacks reported by MathXplore ==

* {{userlinks|Korigosnacks}}

Link spam, [[Special:AbuseLog/315383]] &lt;!-- USERREPORTED:/Korigosnacks/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:32, 6 September 2026 (UTC)
: Stale after only two filter hits and no edits. Please re-report if they spam later. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:56, 6 September 2026 (UTC)
== Athoyislam reported by MathXplore ==

* {{userlinks|Athoyislam}}

Spam &lt;!-- USERREPORTED:/Athoyislam/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:47, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:31, 7 September 2026 (UTC)

== Jamal123lll reported by MathXplore ==

* {{userlinks|Jamal123lll}}

Link spam, [[Special:AbuseLog/315402]] &lt;!-- USERREPORTED:/Jamal123lll/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:48, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:32, 7 September 2026 (UTC)

== Idontknowidkh reported by MathXplore ==

* {{userlinks|Idontknowidkh}}

online shopping spam, [[Special:AbuseLog/315400]] &lt;!-- USERREPORTED:/Idontknowidkh/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:49, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:33, 7 September 2026 (UTC)
== Ridhisharma1999 reported by MathXplore ==

* {{userlinks|Ridhisharma1999}}

Link spam, [[Special:AbuseLog/315435]] &lt;!-- USERREPORTED:/Ridhisharma1999/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:01, 9 September 2026 (UTC)

:{{Done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:02, 9 September 2026 (UTC)
== Thenaoriudaipur reported by MathXplore ==

* {{userlinks|Thenaoriudaipur}}

Link spam, [[Special:AbuseLog/315473]] &lt;!-- USERREPORTED:/Thenaoriudaipur/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:47, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== Networkkingss reported by MathXplore ==

* {{userlinks|Networkkingss}}

Link spam, [[Special:AbuseLog/315458]] &lt;!-- USERREPORTED:/Networkkingss/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:50, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== ~2026-49226-92 reported by MathXplore ==

* {{anonlinks|~2026-49226-92}}

Vandalism &lt;!-- USERREPORTED:/~2026-49226-92/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:57, 10 September 2026 (UTC)
: {{done}}. I also nuked all pages created by this user and their connected temporary accounts based on their associated IP(s). [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:48, 10 September 2026 (UTC)
== ~2026-49632-08 reported by MathXplore ==
* {{anonlinks|~2026-49632-08}}

Spam &lt;!-- USERREPORTED:/~2026-49632-08/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:08, 13 September 2026 (UTC)</text>
      <sha1>46n0x5cf5mpjagnuzgoo979j7jvgabx</sha1>
    </revision>
    <revision>
      <id>4669834</id>
      <parentid>4669806</parentid>
      <timestamp>2026-09-13T06:39:25Z</timestamp>
      <contributor>
        <username>JackPotte</username>
        <id>99248</id>
      </contributor>
      <comment>/* ~2026-49632-08 reported by MathXplore */</comment>
      <origin>4669834</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="15826" sha1="4q6a5z84zov0qxnycie9j58xz70grj4" xml:space="preserve">__NEWSECTIONLINK__ {{Discussion Rooms}} {{shortcut|WB:AN|WB:AA}} {{TOC left}}
{{User:MiszaBot/config
|archive = Wikibooks:Reading room/Administrative Assistance/Archives/%(year)d/%(monthname)s
|algo = old(14d)
|counter = 1
|minthreadstoarchive = 1
|minthreadsleft = 1
}}
{{ombox|type=content|text='''To request a rename or usurpation''', go to the global request page at Meta [[meta:SRUC|here]].&lt;br /&gt;''Please do not post those requests here!''}}
{{Clear}}
Welcome to the '''Administrative Assistance reading room'''.  You can request assistance from [[WB:ADMIN|administrators]] for handling a variety of problems here and alert them about problems which may require special actions not normally used during regular content editing. Please be patient as administrators are often quite busy with either their own projects or trying to perform general maintenance and cleanup.

You can deal with most vandalism yourself: [[Wikibooks:Dealing with vandalism|fix it]], then [[Wikibooks:Templates/User_notices|warn the user]]. If there is repeated vandalism by one user, lots of vandalism on a single page, or vandalism from many users, tell an admin here, or in [irc://irc.freenode.net/wikibooks #wikibooks] (say &lt;code&gt;!admin&lt;/code&gt; to get attention).

For more general questions and assistance that doesn't require an administrator, please use the [[WB:HELP|Assistance Reading Room]].
{{clear}}

[[Category:Reading room]]

== Gloriagulshan reported by MathXplore ==

* {{userlinks|Gloriagulshan}}

[[:w:Wikipedia:Sockpuppet investigations/Kagoz]] ([[Special:Contributions/Tikapara]], [[Wikibooks:Reading_room/Administrative_Assistance/Archives/2025/September#Tikapara_reported_by_MathXplore]]), created page [[Introduction to Filmmaking]] Contributed by Ali Zulfikar Zahedi ([[:w:Ali Zulfikar Zahedi]], [[:w:simple:Ali Zulfikar Zahedi]]) &lt;!-- USERREPORTED:/Gloriagulshan/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 03:56, 29 August 2026 (UTC)

:I believe this page is intended as instructional material for learning filmmaking rather than as an encyclopedic article. I will revise the page to focus on practical filmmaking concepts, methods, and processes in accordance with the purpose of Wikibooks. [[User:Gloriagulshan|Gloriagulshan]] ([[User talk:Gloriagulshan|discuss]] • [[Special:Contributions/Gloriagulshan|contribs]]) 04:20, 29 August 2026 (UTC)
: Cc: {{ping|SHB2000|MarcGarver}} [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:41, 29 August 2026 (UTC)
::I see the account is glocked, and there are no sleepers that aren't already locked, so nothing more to do. [[User:MarcGarver|MarcGarver]] ([[User talk:MarcGarver|discuss]] • [[Special:Contributions/MarcGarver|contribs]]) 11:18, 3 September 2026 (UTC)

== Atlanticgym reported by MathXplore ==

* {{userlinks|Atlanticgym}}

Link spam, [[Special:AbuseLog/315249]] &lt;!-- USERREPORTED:/Atlanticgym/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:32, 29 August 2026 (UTC)

:{{done}} --[[User:SHB2000|SHB2000]] ([[User talk:SHB2000|discuss]] • [[Special:Contributions/SHB2000|contribs]]) 12:35, 29 August 2026 (UTC)
== Makowe2026 reported by Veritas Sapientiae ==

* {{userlinks|Makowe2026}}

Spam &lt;!-- USERREPORTED:/Makowe2026/ --&gt; [[User:Veritas Sapientiae|Veritas Sapientiae]] ([[User talk:Veritas Sapientiae|discuss]] • [[Special:Contributions/Veritas Sapientiae|contribs]]) 13:53, 29 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 19:20, 29 August 2026 (UTC)
== Abir077 reported by MathXplore ==

* {{userlinks|Abir077}}

Link spam, [[Special:AbuseLog/315272]] &lt;!-- USERREPORTED:/Abir077/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:07, 31 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:46, 31 August 2026 (UTC)
== Jeevandan26 reported by MathXplore ==

* {{userlinks|Jeevandan26}}
Link spam, [[Special:AbuseLog/315288]] &lt;!-- USERREPORTED:/Jeevandan26/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:14, 1 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 1 September 2026 (UTC)
== Mohansai00116 reported by MathXplore ==

* {{userlinks|Mohansai00116}}

Link spam, [[Special:AbuseLog/315335]] &lt;!-- USERREPORTED:/Mohansai00116/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:09, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:04, 3 September 2026 (UTC)

== Fatemai6 reported by MathXplore ==

* {{userlinks|Fatemai6}}

Link spam, [[Special:AbuseLog/315329]] &lt;!-- USERREPORTED:/Fatemai6/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:10, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan147 reported by MathXplore ==

* {{userlinks|Kamrulhasan147}}

Link spam, [[Special:AbuseLog/315327]], [[Special:Contributions/Kamrulhasan142]] &lt;!-- USERREPORTED:/Kamrulhasan147/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:12, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan142 reported by MathXplore ==

* {{userlinks|Kamrulhasan142}}

Link spam, [[Special:AbuseLog/315295]], [[Special:Contributions/Kamrulhasan147]] &lt;!-- USERREPORTED:/Kamrulhasan142/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:13, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Twenty7incgs reported by MathXplore ==

* {{userlinks|Twenty7incgs}}

Link spam, [[Special:AbuseLog/315323]] &lt;!-- USERREPORTED:/Twenty7incgs/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:14, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Tailleash reported by MathXplore ==

* {{userlinks|Tailleash}}

Link spam, [[Special:AbuseLog/315318]] &lt;!-- USERREPORTED:/Tailleash/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:15, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Md Akash Mia12 reported by MathXplore ==

* {{userlinks|Md Akash Mia12}}

Link spam, [[Special:AbuseLog/315299]], [[Special:AbuseLog/315298]] &lt;!-- USERREPORTED:/Md Akash Mia12/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:17, 2 September 2026 (UTC)
: {{done|Page deleted}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:03, 3 September 2026 (UTC)

== Vapesitefiftybar reported by MathXplore ==

* {{userlinks|Vapesitefiftybar}}

Link spam, [[Special:AbuseLog/315338]] &lt;!-- USERREPORTED:/Vapesitefiftybar/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:40, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)
== Myteethtime1 reported by MathXplore ==

* {{userlinks|Myteethtime1}}

Spam &lt;!-- USERREPORTED:/Myteethtime1/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:54, 4 September 2026 (UTC)
: {{Done}} by MarcGarver. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)

== Rajstartupservices reported by MathXplore ==

* {{userlinks|Rajstartupservices}}

Link spam, [[Special:AbuseLog/315363]] &lt;!-- USERREPORTED:/Rajstartupservices/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 14:33, 4 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)
== Reazulkarim545456 reported by MathXplore ==

* {{userlinks|Reazulkarim545456}}

Link spam, [[Special:AbuseLog/315377]] &lt;!-- USERREPORTED:/Reazulkarim545456/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:39, 6 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:19, 6 September 2026 (UTC)

== Fahmidafy reported by MathXplore ==

* {{userlinks|Fahmidafy}}

Link spam, [[Special:AbuseLog/315378]] &lt;!-- USERREPORTED:/Fahmidafy/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:40, 6 September 2026 (UTC)
: The filter stopped them three times, no action taken. Please re-report if they continue spamming. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 6 September 2026 (UTC)

== Grow spark digital reported by MathXplore ==

* {{userlinks|Grow spark digital}}

Link spam, [[Special:AbuseLog/315381]] &lt;!-- USERREPORTED:/Grow spark digital/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:42, 6 September 2026 (UTC)
: Only one filter hit, seems stale. Please re-report if they continue to spam. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:49, 6 September 2026 (UTC)

== Korigosnacks reported by MathXplore ==

* {{userlinks|Korigosnacks}}

Link spam, [[Special:AbuseLog/315383]] &lt;!-- USERREPORTED:/Korigosnacks/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:32, 6 September 2026 (UTC)
: Stale after only two filter hits and no edits. Please re-report if they spam later. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:56, 6 September 2026 (UTC)
== Athoyislam reported by MathXplore ==

* {{userlinks|Athoyislam}}

Spam &lt;!-- USERREPORTED:/Athoyislam/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:47, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:31, 7 September 2026 (UTC)

== Jamal123lll reported by MathXplore ==

* {{userlinks|Jamal123lll}}

Link spam, [[Special:AbuseLog/315402]] &lt;!-- USERREPORTED:/Jamal123lll/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:48, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:32, 7 September 2026 (UTC)

== Idontknowidkh reported by MathXplore ==

* {{userlinks|Idontknowidkh}}

online shopping spam, [[Special:AbuseLog/315400]] &lt;!-- USERREPORTED:/Idontknowidkh/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:49, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:33, 7 September 2026 (UTC)
== Ridhisharma1999 reported by MathXplore ==

* {{userlinks|Ridhisharma1999}}

Link spam, [[Special:AbuseLog/315435]] &lt;!-- USERREPORTED:/Ridhisharma1999/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:01, 9 September 2026 (UTC)

:{{Done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:02, 9 September 2026 (UTC)
== Thenaoriudaipur reported by MathXplore ==

* {{userlinks|Thenaoriudaipur}}

Link spam, [[Special:AbuseLog/315473]] &lt;!-- USERREPORTED:/Thenaoriudaipur/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:47, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== Networkkingss reported by MathXplore ==

* {{userlinks|Networkkingss}}

Link spam, [[Special:AbuseLog/315458]] &lt;!-- USERREPORTED:/Networkkingss/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:50, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== ~2026-49226-92 reported by MathXplore ==

* {{anonlinks|~2026-49226-92}}

Vandalism &lt;!-- USERREPORTED:/~2026-49226-92/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:57, 10 September 2026 (UTC)
: {{done}}. I also nuked all pages created by this user and their connected temporary accounts based on their associated IP(s). [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:48, 10 September 2026 (UTC)
== ~2026-49632-08 reported by MathXplore ==
* {{anonlinks|~2026-49632-08}}

Spam &lt;!-- USERREPORTED:/~2026-49632-08/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:08, 13 September 2026 (UTC)
:{{done}} [[User:JackPotte|JackPotte]] ([[User talk:JackPotte|discuss]] • [[Special:Contributions/JackPotte|contribs]]) 06:39, 13 September 2026 (UTC)</text>
      <sha1>4q6a5z84zov0qxnycie9j58xz70grj4</sha1>
    </revision>
    <revision>
      <id>4669855</id>
      <parentid>4669834</parentid>
      <timestamp>2026-09-13T08:10:24Z</timestamp>
      <contributor>
        <username>ArchiverBot</username>
        <id>1227662</id>
      </contributor>
      <minor />
      <comment>Bot: Archiving 2 threads (older than 14 days) to [[Wikibooks:Reading room/Administrative Assistance/Archives/2026/August]]</comment>
      <origin>4669855</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="14830" sha1="qf9ldax1gqmqxz2pcu3vdjsg91pzzoi" xml:space="preserve">__NEWSECTIONLINK__ {{Discussion Rooms}} {{shortcut|WB:AN|WB:AA}} {{TOC left}}
{{User:MiszaBot/config
|archive = Wikibooks:Reading room/Administrative Assistance/Archives/%(year)d/%(monthname)s
|algo = old(14d)
|counter = 1
|minthreadstoarchive = 1
|minthreadsleft = 1
}}
{{ombox|type=content|text='''To request a rename or usurpation''', go to the global request page at Meta [[meta:SRUC|here]].&lt;br /&gt;''Please do not post those requests here!''}}
{{Clear}}
Welcome to the '''Administrative Assistance reading room'''.  You can request assistance from [[WB:ADMIN|administrators]] for handling a variety of problems here and alert them about problems which may require special actions not normally used during regular content editing. Please be patient as administrators are often quite busy with either their own projects or trying to perform general maintenance and cleanup.

You can deal with most vandalism yourself: [[Wikibooks:Dealing with vandalism|fix it]], then [[Wikibooks:Templates/User_notices|warn the user]]. If there is repeated vandalism by one user, lots of vandalism on a single page, or vandalism from many users, tell an admin here, or in [irc://irc.freenode.net/wikibooks #wikibooks] (say &lt;code&gt;!admin&lt;/code&gt; to get attention).

For more general questions and assistance that doesn't require an administrator, please use the [[WB:HELP|Assistance Reading Room]].
{{clear}}

[[Category:Reading room]]

== Gloriagulshan reported by MathXplore ==

* {{userlinks|Gloriagulshan}}

[[:w:Wikipedia:Sockpuppet investigations/Kagoz]] ([[Special:Contributions/Tikapara]], [[Wikibooks:Reading_room/Administrative_Assistance/Archives/2025/September#Tikapara_reported_by_MathXplore]]), created page [[Introduction to Filmmaking]] Contributed by Ali Zulfikar Zahedi ([[:w:Ali Zulfikar Zahedi]], [[:w:simple:Ali Zulfikar Zahedi]]) &lt;!-- USERREPORTED:/Gloriagulshan/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 03:56, 29 August 2026 (UTC)

:I believe this page is intended as instructional material for learning filmmaking rather than as an encyclopedic article. I will revise the page to focus on practical filmmaking concepts, methods, and processes in accordance with the purpose of Wikibooks. [[User:Gloriagulshan|Gloriagulshan]] ([[User talk:Gloriagulshan|discuss]] • [[Special:Contributions/Gloriagulshan|contribs]]) 04:20, 29 August 2026 (UTC)
: Cc: {{ping|SHB2000|MarcGarver}} [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:41, 29 August 2026 (UTC)
::I see the account is glocked, and there are no sleepers that aren't already locked, so nothing more to do. [[User:MarcGarver|MarcGarver]] ([[User talk:MarcGarver|discuss]] • [[Special:Contributions/MarcGarver|contribs]]) 11:18, 3 September 2026 (UTC)

== Abir077 reported by MathXplore ==

* {{userlinks|Abir077}}

Link spam, [[Special:AbuseLog/315272]] &lt;!-- USERREPORTED:/Abir077/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:07, 31 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:46, 31 August 2026 (UTC)
== Jeevandan26 reported by MathXplore ==

* {{userlinks|Jeevandan26}}
Link spam, [[Special:AbuseLog/315288]] &lt;!-- USERREPORTED:/Jeevandan26/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:14, 1 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 1 September 2026 (UTC)
== Mohansai00116 reported by MathXplore ==

* {{userlinks|Mohansai00116}}

Link spam, [[Special:AbuseLog/315335]] &lt;!-- USERREPORTED:/Mohansai00116/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:09, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:04, 3 September 2026 (UTC)

== Fatemai6 reported by MathXplore ==

* {{userlinks|Fatemai6}}

Link spam, [[Special:AbuseLog/315329]] &lt;!-- USERREPORTED:/Fatemai6/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:10, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan147 reported by MathXplore ==

* {{userlinks|Kamrulhasan147}}

Link spam, [[Special:AbuseLog/315327]], [[Special:Contributions/Kamrulhasan142]] &lt;!-- USERREPORTED:/Kamrulhasan147/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:12, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Kamrulhasan142 reported by MathXplore ==

* {{userlinks|Kamrulhasan142}}

Link spam, [[Special:AbuseLog/315295]], [[Special:Contributions/Kamrulhasan147]] &lt;!-- USERREPORTED:/Kamrulhasan142/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:13, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Twenty7incgs reported by MathXplore ==

* {{userlinks|Twenty7incgs}}

Link spam, [[Special:AbuseLog/315323]] &lt;!-- USERREPORTED:/Twenty7incgs/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:14, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Tailleash reported by MathXplore ==

* {{userlinks|Tailleash}}

Link spam, [[Special:AbuseLog/315318]] &lt;!-- USERREPORTED:/Tailleash/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:15, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)

== Md Akash Mia12 reported by MathXplore ==

* {{userlinks|Md Akash Mia12}}

Link spam, [[Special:AbuseLog/315299]], [[Special:AbuseLog/315298]] &lt;!-- USERREPORTED:/Md Akash Mia12/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:17, 2 September 2026 (UTC)
: {{done|Page deleted}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:03, 3 September 2026 (UTC)

== Vapesitefiftybar reported by MathXplore ==

* {{userlinks|Vapesitefiftybar}}

Link spam, [[Special:AbuseLog/315338]] &lt;!-- USERREPORTED:/Vapesitefiftybar/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:40, 2 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:05, 3 September 2026 (UTC)
== Myteethtime1 reported by MathXplore ==

* {{userlinks|Myteethtime1}}

Spam &lt;!-- USERREPORTED:/Myteethtime1/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:54, 4 September 2026 (UTC)
: {{Done}} by MarcGarver. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)

== Rajstartupservices reported by MathXplore ==

* {{userlinks|Rajstartupservices}}

Link spam, [[Special:AbuseLog/315363]] &lt;!-- USERREPORTED:/Rajstartupservices/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 14:33, 4 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 19:28, 4 September 2026 (UTC)
== Reazulkarim545456 reported by MathXplore ==

* {{userlinks|Reazulkarim545456}}

Link spam, [[Special:AbuseLog/315377]] &lt;!-- USERREPORTED:/Reazulkarim545456/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:39, 6 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:19, 6 September 2026 (UTC)

== Fahmidafy reported by MathXplore ==

* {{userlinks|Fahmidafy}}

Link spam, [[Special:AbuseLog/315378]] &lt;!-- USERREPORTED:/Fahmidafy/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:40, 6 September 2026 (UTC)
: The filter stopped them three times, no action taken. Please re-report if they continue spamming. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:20, 6 September 2026 (UTC)

== Grow spark digital reported by MathXplore ==

* {{userlinks|Grow spark digital}}

Link spam, [[Special:AbuseLog/315381]] &lt;!-- USERREPORTED:/Grow spark digital/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 06:42, 6 September 2026 (UTC)
: Only one filter hit, seems stale. Please re-report if they continue to spam. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:49, 6 September 2026 (UTC)

== Korigosnacks reported by MathXplore ==

* {{userlinks|Korigosnacks}}

Link spam, [[Special:AbuseLog/315383]] &lt;!-- USERREPORTED:/Korigosnacks/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:32, 6 September 2026 (UTC)
: Stale after only two filter hits and no edits. Please re-report if they spam later. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 13:56, 6 September 2026 (UTC)
== Athoyislam reported by MathXplore ==

* {{userlinks|Athoyislam}}

Spam &lt;!-- USERREPORTED:/Athoyislam/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:47, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:31, 7 September 2026 (UTC)

== Jamal123lll reported by MathXplore ==

* {{userlinks|Jamal123lll}}

Link spam, [[Special:AbuseLog/315402]] &lt;!-- USERREPORTED:/Jamal123lll/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:48, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:32, 7 September 2026 (UTC)

== Idontknowidkh reported by MathXplore ==

* {{userlinks|Idontknowidkh}}

online shopping spam, [[Special:AbuseLog/315400]] &lt;!-- USERREPORTED:/Idontknowidkh/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:49, 7 September 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 11:33, 7 September 2026 (UTC)
== Ridhisharma1999 reported by MathXplore ==

* {{userlinks|Ridhisharma1999}}

Link spam, [[Special:AbuseLog/315435]] &lt;!-- USERREPORTED:/Ridhisharma1999/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:01, 9 September 2026 (UTC)

:{{Done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:02, 9 September 2026 (UTC)
== Thenaoriudaipur reported by MathXplore ==

* {{userlinks|Thenaoriudaipur}}

Link spam, [[Special:AbuseLog/315473]] &lt;!-- USERREPORTED:/Thenaoriudaipur/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:47, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== Networkkingss reported by MathXplore ==

* {{userlinks|Networkkingss}}

Link spam, [[Special:AbuseLog/315458]] &lt;!-- USERREPORTED:/Networkkingss/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:50, 10 September 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:49, 10 September 2026 (UTC)

== ~2026-49226-92 reported by MathXplore ==

* {{anonlinks|~2026-49226-92}}

Vandalism &lt;!-- USERREPORTED:/~2026-49226-92/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:57, 10 September 2026 (UTC)
: {{done}}. I also nuked all pages created by this user and their connected temporary accounts based on their associated IP(s). [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] /// [[User talk:Codename Noreste|⭐️✨]] 14:48, 10 September 2026 (UTC)
== ~2026-49632-08 reported by MathXplore ==

* {{anonlinks|~2026-49632-08}}

Spam &lt;!-- USERREPORTED:/~2026-49632-08/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:08, 13 September 2026 (UTC)
:{{done}} [[User:JackPotte|JackPotte]] ([[User talk:JackPotte|discuss]] • [[Special:Contributions/JackPotte|contribs]]) 06:39, 13 September 2026 (UTC)</text>
      <sha1>qf9ldax1gqmqxz2pcu3vdjsg91pzzoi</sha1>
    </revision>
  </page>
  <page>
    <title>Getting Started as an Entrepreneur/Money/Finding the Money</title>
    <ns>0</ns>
    <id>175680</id>
    <revision>
      <id>4669866</id>
      <parentid>4663675</parentid>
      <timestamp>2026-09-13T09:26:44Z</timestamp>
      <contributor>
        <username>~2026-49512-40</username>
        <id>3625842</id>
      </contributor>
      <comment>Add section on startup credits and cloud credits, with citation to the Sourcey registry</comment>
      <origin>4669866</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="10947" sha1="f4n2fkk6wuvqu440bf2j6yu2sxnisco" xml:space="preserve">== '''Finding the Money''' ==
 
'''Where do I find money?'''&lt;br&gt; 
As your parents have helpfully pointed out, it doesn’t grow on trees. But here are a few leaves you can turn over to find potential investors. 
 
'''Business plan competitions'''&lt;br&gt; 
Numerous colleges, universities and companies offer business plan competitions open to students from all institutions. Browse the Internet and check out entrepreneurship web sites for more resources. If your school runs a business plan competition, get involved. Not only do you get a chance to win some hard cash for your business, you have a motive to get your business plan written, and probably some guidelines to help you make it work. 
 
'''Venture forums'''&lt;br&gt; 
A venture forum is an educational program designed to help entrepreneurs at various stages of business development. One of the best-known examples is the MIT Enterprise Forum. The Forum has twenty-three chapters nationally and internationally and offers seminars and online publications. 

Search the Internet for more venture forums, or call your local Chamber of Commerce to find out what’s happening in your area. 
 
'''Venture fairs'''&lt;br&gt; 
Venture fairs have been around for years, but, according to David Freschman, President of the Delaware Innovation Fund and chairman of a venture fair known as Early Stage East, an increasing number of venture capital fairs are catering to early-stage businesses. These fairs are attended by individual angel investors, and early-stage venture capitalists. They help entrepreneurs increase the number of investors exposed to their companies, and compress the time frame for raising critical early-stage financing. 

Venues for pitching to investors at venture fairs include social receptions, display booths, meals where tables are clearly marked as “owned” by entrepreneurs (investors get to choose who they sit with), and formal presentations. 
 
'''Talk to your professors'''&lt;br&gt; 
Although academics aren’t known for having access to a boatload of cash, try talking to your professors. Some professors are in fact interested in investing in student projects. Others may have contacts in the business world and may be able to introduce you to potentially interested funders. 
 
'''Talk with alumni'''&lt;br&gt; 
Ask the alumni relations office for help in contacting people in your field. If your school has an entrepreneurship club, some of these contacts may already have been made. Even if you don’t find immediate funding through alumni, the contacts you make may lay fertile ground for the future. 
 
'''Your friends, your parents, your friends’ parents'''&lt;br&gt; 
Tell everyone what you’re up to. Getting the word out is key to getting what you need for funding. Let people know that you’re looking for funding resources, and make it clear what you’re expecting to give in return. People like to help people, and many people are natural connection-makers. The more you talk about your work and your funding needs, the greater the chances that you’ll stumble upon the right person. 

'''Grants'''&lt;br&gt; 
Grants are inexpensive: there is no interest charged, no need to pay it back, and you don’t give up any equity (more on equity in the next section). There are two popular government programs that give grants to high-tech companies: SBIR (Small Business Innovation Research Program) and STTR (Small Business Technology Transfer Program). These grants are distributed in two major phases, with the first providing up to $100K to pay for a proof of concept, and the second up to $1 million for prototype development. Solicitations are usually twice a year; many workshops around the country provide information on applying for the grants. (For a good explanation and more information on SBIR/STTR, visit their website.) 

A Cooperative Research &amp; Development Agreement (CRADA) is a grant in which a government lab works with a company to develop or test a particular technology/product. The government doesn’t provide any money to the company, but CRADAs can be an excellent way to obtain skills and equipment, and to test a product. For more information on CRADAs, see their website. 

And then of course there is the world of private grants. There are numerous foundations and other organizations around the country (including the NCIIA) that provide funds to technology entrepreneurs. Several websites are devoted to this topic—The Foundation Center  is a good starting place. Also, see below to start learning about what an NCIIA grant can do for you. 


{| WIDTH=&quot;75%&quot;| style=&quot;background-color: #f2fff2;{{Text default color}}; border: solid 1px #bfffbf; padding: 1em;&quot; valign=top|
|

'''How one E-Team found the money'''&lt;br&gt; 
A recent E-Team success story comes from Huntington, West Virginia. Vandalia Research, Inc., founded by two Marshall University undergraduates and funded in part by NCIIA, is in the process of successfully commercializing technology for the mass production of DNA sequences. Team leader Derek Gregg on how they got through their initial seed round: 

&quot;We got all of our funding from local investors in Huntington. We worked on a business plan with a Marshall alum for about nine months, then took the plan to a community forum of about fifty angel investors. We were able to secure all of our funding in that one three-hour meeting! We were shooting for 500k in funding, actually, and ended up oversubscribing substantially.&quot; 

&quot;The first round money is going to be used primarily for renovations and equipment purchases to get the manufacturing facility up and running. We also hired our first full-time employee, a lab technician who will also head up the research end. We've started discussions with some local regional venture capital firms for our next round of funding. As far as long-term goals go, our business model is to use our technology to do custom, in-house DNA manufacturing for anyone who needs it.&quot;


'''About NCIIA Advanced E-Team grants'''&lt;br&gt;  
Advanced E-Team grants provide student teams with the support they need to bring an innovative product or technology from idea to prototype, and eventually to market. Successful E-Team grant proposals demonstrate an idea's technical feasibility, social value, and potential for commercialization. Advanced E-Team grants range in size from $1,000 to $20,000; the grant period is twelve to eighteen months. Annual application deadlines are in December and May. 

We favor Advanced E-Team grant proposals that:
 
* Show a strong likelihood of developing innovations with realistic, well-documented technological and commercial promise 
* Lead to the development of a product or technology designed for affordability, that directly benefits human health or the environment, or that follows a sustainable, socially motivated business model 
* Demonstrate knowledge of the market and evidence of consumer interest 
* Involve a balanced, multidisciplinary E-Team, including students, faculty, and advisors from technical, business, and humanities disciplines 
* Reflect the diversity of the home institution, and actively engage faculty and students from groups traditionally underrepresented in invention, innovation, and entrepreneurship, including women and minorities 
* Create opportunities for high-quality group learning experiences 
* Create viable collaborative opportunities for participants from both academe and industry 
* Incorporate a plan and a budget that are reasonable, achievable, and sustainable 
* Demonstrate strong team commitment and faculty and institutional support 
 
Visit http://www.nciia.org for more details!

|}

{| border=&quot;0&quot; width=&quot;100%&quot;
|-
| &lt;&lt; [[Getting_Started_as_an_Entrepreneur/Money/Bootstrapping|Bootstrapping]] || align=&quot;right&quot; | [[Getting_Started_as_an_Entrepreneur/Money/Debt and Equity|Debt and Equity]] &gt;&gt;
|}

{{BookCat}}'''Startup credits and cloud credits'''&lt;br&gt;
Not every dollar has to come from an investor. The companies you build on also want you around, and a lot of them pay you to stay. Cloud providers, AI vendors, and a long tail of software companies run startup programs that hand out credits, free tiers, and discounts to new businesses, usually in exchange for building on their platform and occasionally telling other founders about it.

The big cloud programs are the most generous. AWS Activate, Microsoft Azure for Startups, and Google Cloud's startup offerings can put anywhere from a few thousand to well over a hundred thousand dollars of credits on a young company's account, and each one bundles extras like training, office hours with engineers, and sometimes cash prizes or co-marketing. AI vendors moved fast once agents started spending money. Anthropic, OpenAI, and the model labs behind them now run credit programs aimed at startups building on their APIs, and the amounts are large enough to cover a year of inference for a small product. Beyond the headline names, hundreds of SaaS companies offer startup pricing, from free annual licenses to steep percentage discounts. The programs change often, so a list copied from last year is already half wrong.

Treat credits like the cash they are, with two caveats. First, they expire. A credit grant is usually good for one to two years, and some programs cap how much you can spend per month, so plan the burn the way you would plan a bank account. Second, they are locked to one vendor. A hundred thousand dollars of cloud credits will not pay your payroll, and the moment you design around one provider's free tier you inherit its lock in. Use credits to buy time: run the infrastructure you would have bought anyway, defer the cash spend, and keep the option to move.

Applying is mostly paperwork. Most programs ask for a short description of the product, the stage of the company, annual revenue, and a link to something real, and the review takes days to weeks. Applying early helps, because the biggest grants go to companies that are still small enough to qualify, and revenue caps are the most common reason an otherwise strong application gets declined. If you are between programs, compare what each one actually gives you before you commit, because the fine print is where the value hides.

If you want to see what is on the table before you apply, the open registry at [[https://sourcey.com|Sourcey]] tracks the offers across hundreds of vendors, with the source URL and the date each fact was read, and it publishes the whole thing under a CC BY 4.0 license. As of September 2026 the registry lists 486 offers across 433 vendors. The same site grades whether a service is usable by an AI agent at all, that is, whether a program can sign up, pay, and operate it without a person in the loop, which matters more every year as agents start doing the buying. It also ships an open source documentation generator that turns OpenAPI, MCP, and code documentation into a static site, useful if you are building the API side of things.</text>
      <sha1>f4n2fkk6wuvqu440bf2j6yu2sxnisco</sha1>
    </revision>
    <revision>
      <id>4669872</id>
      <parentid>4669866</parentid>
      <timestamp>2026-09-13T09:46:41Z</timestamp>
      <contributor>
        <username>~2026-49516-60</username>
        <id>3625843</id>
      </contributor>
      <comment>Fix external link syntax for the Sourcey citation</comment>
      <origin>4669872</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="10945" sha1="3ah5d17ueewb2srbv8r0upqx0p4dxf7" xml:space="preserve">== '''Finding the Money''' ==
 
'''Where do I find money?'''&lt;br&gt; 
As your parents have helpfully pointed out, it doesn’t grow on trees. But here are a few leaves you can turn over to find potential investors. 
 
'''Business plan competitions'''&lt;br&gt; 
Numerous colleges, universities and companies offer business plan competitions open to students from all institutions. Browse the Internet and check out entrepreneurship web sites for more resources. If your school runs a business plan competition, get involved. Not only do you get a chance to win some hard cash for your business, you have a motive to get your business plan written, and probably some guidelines to help you make it work. 
 
'''Venture forums'''&lt;br&gt; 
A venture forum is an educational program designed to help entrepreneurs at various stages of business development. One of the best-known examples is the MIT Enterprise Forum. The Forum has twenty-three chapters nationally and internationally and offers seminars and online publications. 

Search the Internet for more venture forums, or call your local Chamber of Commerce to find out what’s happening in your area. 
 
'''Venture fairs'''&lt;br&gt; 
Venture fairs have been around for years, but, according to David Freschman, President of the Delaware Innovation Fund and chairman of a venture fair known as Early Stage East, an increasing number of venture capital fairs are catering to early-stage businesses. These fairs are attended by individual angel investors, and early-stage venture capitalists. They help entrepreneurs increase the number of investors exposed to their companies, and compress the time frame for raising critical early-stage financing. 

Venues for pitching to investors at venture fairs include social receptions, display booths, meals where tables are clearly marked as “owned” by entrepreneurs (investors get to choose who they sit with), and formal presentations. 
 
'''Talk to your professors'''&lt;br&gt; 
Although academics aren’t known for having access to a boatload of cash, try talking to your professors. Some professors are in fact interested in investing in student projects. Others may have contacts in the business world and may be able to introduce you to potentially interested funders. 
 
'''Talk with alumni'''&lt;br&gt; 
Ask the alumni relations office for help in contacting people in your field. If your school has an entrepreneurship club, some of these contacts may already have been made. Even if you don’t find immediate funding through alumni, the contacts you make may lay fertile ground for the future. 
 
'''Your friends, your parents, your friends’ parents'''&lt;br&gt; 
Tell everyone what you’re up to. Getting the word out is key to getting what you need for funding. Let people know that you’re looking for funding resources, and make it clear what you’re expecting to give in return. People like to help people, and many people are natural connection-makers. The more you talk about your work and your funding needs, the greater the chances that you’ll stumble upon the right person. 

'''Grants'''&lt;br&gt; 
Grants are inexpensive: there is no interest charged, no need to pay it back, and you don’t give up any equity (more on equity in the next section). There are two popular government programs that give grants to high-tech companies: SBIR (Small Business Innovation Research Program) and STTR (Small Business Technology Transfer Program). These grants are distributed in two major phases, with the first providing up to $100K to pay for a proof of concept, and the second up to $1 million for prototype development. Solicitations are usually twice a year; many workshops around the country provide information on applying for the grants. (For a good explanation and more information on SBIR/STTR, visit their website.) 

A Cooperative Research &amp; Development Agreement (CRADA) is a grant in which a government lab works with a company to develop or test a particular technology/product. The government doesn’t provide any money to the company, but CRADAs can be an excellent way to obtain skills and equipment, and to test a product. For more information on CRADAs, see their website. 

And then of course there is the world of private grants. There are numerous foundations and other organizations around the country (including the NCIIA) that provide funds to technology entrepreneurs. Several websites are devoted to this topic—The Foundation Center  is a good starting place. Also, see below to start learning about what an NCIIA grant can do for you. 


{| WIDTH=&quot;75%&quot;| style=&quot;background-color: #f2fff2;{{Text default color}}; border: solid 1px #bfffbf; padding: 1em;&quot; valign=top|
|

'''How one E-Team found the money'''&lt;br&gt; 
A recent E-Team success story comes from Huntington, West Virginia. Vandalia Research, Inc., founded by two Marshall University undergraduates and funded in part by NCIIA, is in the process of successfully commercializing technology for the mass production of DNA sequences. Team leader Derek Gregg on how they got through their initial seed round: 

&quot;We got all of our funding from local investors in Huntington. We worked on a business plan with a Marshall alum for about nine months, then took the plan to a community forum of about fifty angel investors. We were able to secure all of our funding in that one three-hour meeting! We were shooting for 500k in funding, actually, and ended up oversubscribing substantially.&quot; 

&quot;The first round money is going to be used primarily for renovations and equipment purchases to get the manufacturing facility up and running. We also hired our first full-time employee, a lab technician who will also head up the research end. We've started discussions with some local regional venture capital firms for our next round of funding. As far as long-term goals go, our business model is to use our technology to do custom, in-house DNA manufacturing for anyone who needs it.&quot;


'''About NCIIA Advanced E-Team grants'''&lt;br&gt;  
Advanced E-Team grants provide student teams with the support they need to bring an innovative product or technology from idea to prototype, and eventually to market. Successful E-Team grant proposals demonstrate an idea's technical feasibility, social value, and potential for commercialization. Advanced E-Team grants range in size from $1,000 to $20,000; the grant period is twelve to eighteen months. Annual application deadlines are in December and May. 

We favor Advanced E-Team grant proposals that:
 
* Show a strong likelihood of developing innovations with realistic, well-documented technological and commercial promise 
* Lead to the development of a product or technology designed for affordability, that directly benefits human health or the environment, or that follows a sustainable, socially motivated business model 
* Demonstrate knowledge of the market and evidence of consumer interest 
* Involve a balanced, multidisciplinary E-Team, including students, faculty, and advisors from technical, business, and humanities disciplines 
* Reflect the diversity of the home institution, and actively engage faculty and students from groups traditionally underrepresented in invention, innovation, and entrepreneurship, including women and minorities 
* Create opportunities for high-quality group learning experiences 
* Create viable collaborative opportunities for participants from both academe and industry 
* Incorporate a plan and a budget that are reasonable, achievable, and sustainable 
* Demonstrate strong team commitment and faculty and institutional support 
 
Visit http://www.nciia.org for more details!

|}

{| border=&quot;0&quot; width=&quot;100%&quot;
|-
| &lt;&lt; [[Getting_Started_as_an_Entrepreneur/Money/Bootstrapping|Bootstrapping]] || align=&quot;right&quot; | [[Getting_Started_as_an_Entrepreneur/Money/Debt and Equity|Debt and Equity]] &gt;&gt;
|}

{{BookCat}}'''Startup credits and cloud credits'''&lt;br&gt;
Not every dollar has to come from an investor. The companies you build on also want you around, and a lot of them pay you to stay. Cloud providers, AI vendors, and a long tail of software companies run startup programs that hand out credits, free tiers, and discounts to new businesses, usually in exchange for building on their platform and occasionally telling other founders about it.

The big cloud programs are the most generous. AWS Activate, Microsoft Azure for Startups, and Google Cloud's startup offerings can put anywhere from a few thousand to well over a hundred thousand dollars of credits on a young company's account, and each one bundles extras like training, office hours with engineers, and sometimes cash prizes or co-marketing. AI vendors moved fast once agents started spending money. Anthropic, OpenAI, and the model labs behind them now run credit programs aimed at startups building on their APIs, and the amounts are large enough to cover a year of inference for a small product. Beyond the headline names, hundreds of SaaS companies offer startup pricing, from free annual licenses to steep percentage discounts. The programs change often, so a list copied from last year is already half wrong.

Treat credits like the cash they are, with two caveats. First, they expire. A credit grant is usually good for one to two years, and some programs cap how much you can spend per month, so plan the burn the way you would plan a bank account. Second, they are locked to one vendor. A hundred thousand dollars of cloud credits will not pay your payroll, and the moment you design around one provider's free tier you inherit its lock in. Use credits to buy time: run the infrastructure you would have bought anyway, defer the cash spend, and keep the option to move.

Applying is mostly paperwork. Most programs ask for a short description of the product, the stage of the company, annual revenue, and a link to something real, and the review takes days to weeks. Applying early helps, because the biggest grants go to companies that are still small enough to qualify, and revenue caps are the most common reason an otherwise strong application gets declined. If you are between programs, compare what each one actually gives you before you commit, because the fine print is where the value hides.

If you want to see what is on the table before you apply, the open registry at [https://sourcey.com Sourcey] tracks the offers across hundreds of vendors, with the source URL and the date each fact was read, and it publishes the whole thing under a CC BY 4.0 license. As of September 2026 the registry lists 486 offers across 433 vendors. The same site grades whether a service is usable by an AI agent at all, that is, whether a program can sign up, pay, and operate it without a person in the loop, which matters more every year as agents start doing the buying. It also ships an open source documentation generator that turns OpenAPI, MCP, and code documentation into a static site, useful if you are building the API side of things.</text>
      <sha1>3ah5d17ueewb2srbv8r0upqx0p4dxf7</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/User/DOS</title>
    <ns>0</ns>
    <id>179092</id>
    <revision>
      <id>4669817</id>
      <parentid>4604590</parentid>
      <timestamp>2026-09-13T06:22:25Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669817</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="39163" sha1="b9am5r63m2xuv8qruzqc76dva7g8so2" xml:space="preserve">{{ArosNav}}


==Beginners Tutorial / Basic Usage==

By default, the current directory is being displayed as part of the shell prompt. By default, the starting point is 'System:', the OS's root directory also known as sys:  

&lt;code&gt;System:&gt;&lt;/code&gt;

Type 'dir' and hit return. You will see the contents of the current directory.

&lt;code&gt;System:&gt;dir&lt;/code&gt;

You can run an executable or enter a directory just by typing its name (and hitting return). Enter the 'C' directory simply by typing 'c' (AROS DOS is case insensitive):

&lt;code&gt;System:&gt;c&lt;/code&gt;

Now press the up-arrow button twice. AROS shell has got a command history, which allows you to repeat or re-use commands quickly. Now you should see the 'dir' command again, so hit return. You will see the contents of the 'c' directory you've just entered.

&lt;code&gt;System:c&gt;dir&lt;/code&gt;

This directory is AROS's primary location for executables which can be run from any directory. Now type '/' (just a slash) and hit return. You've just moved up one directory, back to 'System:'

&lt;code&gt;System:&gt;&lt;/code&gt;

Now try another 'dir' like command (which resides in the 'c' directory), 'list':

&lt;code&gt;System:&gt;list&lt;/code&gt;

The output is quite the same as 'dir'. But you can control the 'list' output with options. AROS DOS command line options are recognized by their name, and eventually their position on the command line. Try this:

&lt;code&gt;System:&gt;list sub d&lt;/code&gt;

The output will now consist of all the directories contents which names contain the substring 'd'. Another example, another option:

&lt;code&gt;System:&gt;list sub d all&lt;/code&gt;

This will list the contents matching 'd' recursively.


==AROS dos script scripting==

Have a look [https://aminet.net/search?query=ados here for more] 

&lt;syntaxhighlight lang=&quot;text&quot;&gt;
IF &lt;condition&gt;
; these commands are executed if the condition is true
ELSE
; these commands are executed if the condition is false
ENDIF
&lt;/syntaxhighlight&gt;

&lt;condition&gt; can be one of

&lt;code&gt;WARN&lt;/code&gt; - return code of the previous command is 5 or higher.

&lt;code&gt;ERROR&lt;/code&gt; - return code of the previous command is 10 or higher.

&lt;code&gt;FAIL&lt;/code&gt; - return code of the previous command is 20 or higher.

&lt;code&gt;EXISTS &lt;filename&gt;&lt;/code&gt; - check if file or directory exists.

&lt;code&gt;''&lt;a&gt;'' '''EQ''' ''&lt;nowiki&gt;&lt;b&gt;&lt;/nowiki&gt;''&lt;/code&gt; - string comparison.

&lt;code&gt;''&lt;a&gt;'' '''EQ''' ''&lt;nowiki&gt;&lt;b&gt;&lt;/nowiki&gt;''&lt;/code&gt; VAL - numeric comparison.

&lt;code&gt;''&lt;a&gt;'' '''GT''' ''&lt;nowiki&gt;&lt;b&gt;&lt;/nowiki&gt;''&lt;/code&gt; - same as EQ, just means &quot;greater than&quot;.

&lt;code&gt;''&lt;a&gt;'' '''GE''' ''&lt;nowiki&gt;&lt;b&gt;&lt;/nowiki&gt;''&lt;/code&gt; - same as EQ, just means &quot;greater or equal&quot;.

any of the above can be negated by NOT.
e.g. use NOT GT for &quot;less or equal&quot; or NOT GE for &quot;less than&quot;.


==Drives, Files, Assigns, Directories==

A certain set of directories and files needed by the operating system will be present in every AROS distribution. Additionally, &quot;assigns&quot; (logical, not physical, drives) point to physical drive's partitions or locations in the partition's directory structure.


===Physical drives===
:By default harddrives on the IDE bus are assigned the drive names &quot;DH0:&quot;, &quot;DH1:&quot;, etc.
:By default USB pendrives are assigned the drive names &quot;DU0:&quot;, &quot;DU1:&quot;, etc.
:By default CD / DVD drives on the IDE bus are assigned the drive names &quot;CD0:&quot;, &quot;CD1:&quot;, etc.


===Logical drives, &quot;assigns&quot;===
&lt;code&gt;
SYS:
Extras:
DEVS:
Development:
L:
S:
LIBS:
C:
ENV:
RAM:
ENVARC:
MUI:
T:
&lt;/code&gt;


===Directories and files===

===The AROS shell===

In Dopus 5 Magellan - right mouse click -&gt; Icaros -&gt; Shell 

In Wanderer (AROS Desktop / GUI), hit RightAROS + w (or F12 + w) (or use right mousebutton to access Wanderer's menu on the top of the screen) to open a shell window. To close the shell window, click on the top left X of the shell window or type in 

 endcli

or 

 endshell


==== SYS:Prefs ====

...contains all system preferences programs, like &quot;Screenmode&quot;, &quot;Locale&quot;, &quot;Time&quot;, &quot;Trident&quot; (USB), etc.
Is part of default path, thus entering &quot;screenmode&quot; in shell will bring up &quot;Screenmode&quot; prefs program.


==== SYS:Devs ====

...contains device drivers and datatypes. Move a file to the corresponding subdirectory of &quot;SYS:Storage&quot; to disable it (after reboot). More (currently disabled) device drivers or datatypes may be found unter &quot;SYS:Storage&quot;, move to &quot;Devs:&quot; to enable (after reboot).

==== SYS:Storage ====

...is a directory meant to store optional or currently unused devices and datatypes.
Move contents of &quot;Devs:&quot; (see above) here to disable device drivers (after reboot).


==== S:startup-sequence ====

...is a script that will be run when starting up the operating system. It is also used by some applications to store their individual requirements (if any - mosty this will be a line like &quot;assign PROGRAMNAME: SYS:path/to/installation/of/PROGRAMNAME&quot;)


==== S:user-startup ====

...is a script that will be run by S:startup-sequence. It's the place to put your own stuff. Imagine you have some executable programs installed in a different directory than &quot;C:&quot; (or any other in default &quot;path&quot;) but still want to access them without typing their full paths, you may add a line like this: &quot;path WORK:path/to/my/program/ add&quot;.

It is also used by some applications to store their individial requirements (see above).


==== S:shell-startup ====

...is a script that will be run when starting up a new shell. By default, it contains commands that define the look of your shell prompt. See description of 'prompt' command.


==AROS DOS Commands Reference==

Another list of [http://www.pjhutchison.org/emulation/uae_amigados.html Dos commands]

{| class=&quot;wikitable&quot;
!Key
!desc
|----
|/A
| Required argument
|----
|/F
| Final argument in list
|----
|/K
| Keyword must be entered with argument
|----
|/M
| Multiple arguments
|----
|/N
| Number
|----
|/S
| Switch (optional)
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
! colspan=&quot;2&quot; |Addbuffers
|----
|width=&quot;20%&quot;| Format:
| Addbuffers Drive/A Buffers/N
|----
|Purpose:
| Add memory to disk buffers to improve speed.
|----
|Parameters:
| 
;Drive: Name of drive
;Buffers: Number of 512k buffers to add.
|----
|Example:
| Addbuffers DH0: 10
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |AddDatatypes
|----
|width=&quot;20%&quot;| Format:
| AddDataTypes files/M QUIET/S REFRESH/S LIST/S
|----
|Purpose:
| Activates datatypes or adds another datatype if not detected at startup
|----
|Parameters:
| 
;files: List of datatypes to add, 
;Quiet: No output, 
;Refresh: Update datatypes.
|----
|Example:
| AddDataTypes gif.datatype REFRESH
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Alias
|----
|width=&quot;20%&quot;| Format:
| Alias Name String/F
|----
|Purpose:
| Assigns a short name to a dos command.
|----
|Parameters:
| 
;Name: Alias name, 
;String: String or command to use for alias.
|----
|Example:
| Alias Del Delete
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Ask
|----
|width=&quot;20%&quot;| Format:
| Ask Prompt/A
|----
|Purpose:
| Asks a question in a script (reply y/n). Use IF WARN to test for a yes (value 5).
|----
|Parameters:
| 
;Prompt: Text to be displayed.
|----
|Example:
| Ask &quot;Are you sure? Y/n&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Assign
|----
|width=&quot;20%&quot;| Format:
| Assign Name Target/M LIST/S EXISTS/S DISMOUNT/S DEFER/S PATH/S ADD/S REMOVE/S
|----
|
| VOLS/S DIRS/S DEVICES/S
|----
|Purpose:
| Assign names to directory paths.
|----
|Parameters:
|
;Name: Name of the assign, 
;Target: Directory path, 
;List: Display list of assigns
;Exists: Test if assign exists (use IF WARN), 
;Dismount: Remove assign
;Defer: Assign later
;Path: Add assign with path,
;Add: Add a new target to existing path (like LIBS:)
;Remove:Remove an assign,
;Vols: List volumes, 
;Dirs:List directories, 
;Devices: List devices.
|----
|Example:
| Assign Development: Extras:bin
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Avail
|----
|width=&quot;20%&quot;| Format:
| Avail CHIP/S FAST/S TOTAL/S FLUSH/S
|----
|Purpose:
| Memory availability
|----
|Parameters:
| 
;Chip: Display chip memory
;Fast: Display fast memory
;Total: Display all memory 
;Flush: Free up memory
|----
|Example:
| Avail TOTAL
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Break
|----
|width=&quot;20%&quot;| Format:
| Break Process/A/N ALL/S C/S D/S E/S F/S
|----
|Purpose:
| Stop a program (see Status)
|----
|Paramters:
| 
;Process: Process name or Port
;All: Apply C,D,E and F
;C: Apply Ctrl+C
;D: Apply Ctrl+d
;E: Apply Ctrl+E
;F: Apply Ctrl+F
|----
|Example:
| Break 2 C
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |CD
|----
|width=&quot;20%&quot;| Format:
| CD Dir/A
|----
|Purpose:
| Change directory
|----
|Parameters:
|
;Dir: Directory to change to
|----
|Example:
| CD Text_Files
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |ChangeTaskPri
|----
|width=&quot;20%&quot;| Format:
| ChangeTaskPri Pri=Priority/A/N Process/K/N
|----
|Purpose:
| Changes program's execution priority (see Status)
|----
|Parameters:
| 
;Pri: Priority to apply (-128 to +127) 
;Process: Process number (see Status)
|----
|Example:
| ChangeTaskPri 2 1
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Conclip
|----
|width=&quot;20%&quot;| Format:
| Conclip Unit/N OFF/S
|----
|Purpose:
| Activates clipboard device
|----
|Parameters:
| 
;Unit: Clipboard unit
;Off: Turn off clipboard
|----
|Example:
| Conclip 1
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Copy
|----
|width=&quot;20%&quot;| Format:
| Copy From/M To/A ALL/S QUIET/S BUF=BUFFER/K/N CLONE/S DATES/S NOPRO/S COM/S NOREQ/S
|----
|Purpose:
| Copy files (with/without protection bits)
|----
|Parameters:
| 
;From: Files to copy, 
;To: Directory or file to copy to
;All: Copy all files,
;Quiet: No output, 
;Buffer: Size of buffer (default = 100K)
;Clone: Copy file and datestamp, protect bits and comment
;Dates:  Copy datestamp as well
;NoPro: Set default protection bits
;Com: Copy comment 
;NoReq: No requester popups
|----
|Example:
| Copy mydoc.txt docs: Dates
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Date
|----
|width=&quot;20%&quot;| Format:
| Date Day Date Time To=Ver/K
|----
|Purpose:
| Display/change date or time
|----
|Parameters:
| 
;Day: Day of the Week, 
;Date: Date in dd-mmm-yy format
;Time: Time in hh:mm[:ss] format
;To: Save to filename
|----
|Example:
| Date To=date.txt
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Delete
|----
|width=&quot;20%&quot;| Format:
| Delete File/M/A ALL/S QUIET/S FORCE/S
|----
|Purpose:
| Delete files and/or directories.
|----
|Parameters:
| 
;Files: One or more files
;All: Delete all subfolders and files
;Quiet: No output
;Force: Ignore protection flags when deleting
|----
|Example:
| Delete OldFilesDir All
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Dir
|----
|width=&quot;20%&quot;| Format:
| Dir Dir Opt/K ALL/S DIRS/S FILES/S INTER/S
|----
|Purpose:
| List contents of a directory
|----
|Parameters:
| 
;Dir: Directory
;Opt: Option
;Dirs: List directories
;Files: List Files
;Inter: Interactive mode.
|----
|Example:
| Dir S: Files
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Diskchange
|----
|width=&quot;20%&quot;| Format:
| Diskchange Device/A
|----
|Purpose:
| Tell Dos that a disk has been swapped in a non-autosensing disk drive.
|----
|Parameters:
|
;Device: Name of removable device.
|----
|Example:
| Diskchange DU2:
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Echo
|
|----
|width=&quot;20%&quot;| Format:
| Echo String/M NOLINE/S FIRST/K/N LEN/K/N TO/K
|----
|Purpose:
| Display text in a script or part of a string of text.
|----
|Parameters:
| 
;String: Text to display
;NoLine: Do not print a new line
;First: Position of first character
;Len: Length of substring 
;To: Destination file
|----
|Example:
| Echo &quot;Enter your name: &quot; NoLine
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Else
|----
|width=&quot;20%&quot;| Format:
| Else
|----
|Purpose:
| Used with IF, if not true do these commands
|----
|Example:
| 
&lt;code&gt;
If Exists s:User-Startup
Else
Endif
&lt;/code&gt;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |EndCLI
|----
|width=&quot;20%&quot;| Format:
| EndCLI
|----
|Purpose:
| Close CLI console window
|----
|Example:
| EndCLI
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Endif
|----
|width=&quot;20%&quot;| Format:
| Endif
|----
|Purpose:
| End a IF..ELSE..ENDIF block
|----
|Example:
| If $Age GT 65 
Else
Endif
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Endskip
|----
|width=&quot;20%&quot;| Format:
| Endskip
|----
|Purpose:
| Stops a SKIP branch (for debugging)
|----
|Example:
| Endskip
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Eval
|----
|width=&quot;20%&quot;| Format:
| Eval Value1/A Op Value2/M To/K LFormat/K
|----
|Purpose:
| Evaluate a simple arithmetic expression
|----
|Parameters:
| 
;Value1, Value2:  Values to evaluate (Decimal, Hex (0xn) or Octal (0nnn),
;Op: Operlexiaation (+,-,*,/,^,%),  
;To: File to save result,
;LFormat: Output format string (use *n to give a line feed).
|----
|Example:
| Eval $count + 1 to env:count
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Execute
|----
|width=&quot;20%&quot;| Format:
| Execute File/A
|----
|Purpose:
| Execute a script or batch file
|----
|Parameters:
|
;File: Script file to execute
|----
|Example:
| Execute PCD
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Failat
|----
|width=&quot;20%&quot;| Format:
| Failat RCLIM/A
|----
|Purpose:
| Change failure limit for scripts (0,5,10,20)
|----
|
| (0 - Ok, 5 - Warn, 10 - Error, 20 - Fail)
|----
|Parameters:
|
;RCLIM: Failat number (0-20)
|----
|Example:
| Failat 20
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Fault
|----
|width=&quot;20%&quot;| Format:
| Fault Error/N/M
|----
|Purpose:
| Display error message from a code
|----
|Parameters:
|
;Error: One or more error numbers
|----
|Example:
| Fault 221
|----
|
| &quot;Fault 221: Disk is full&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |FileNote
|----
|width=&quot;20%&quot;| Format:
| Filenote File/A Comment ALL/S QUIET/S
|----
|Purpose:
| Attach a comment to a file (see LIST)
|----
|Parameters:
|
;File: File to add comment to
;Comment: Text to apply
;All: Apply to all files, 
;Quiet: No output
|----
|Example:
| FileNote List.txt &quot;A list of people's names&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Format
|----
|width=&quot;20%&quot;| Format:
| Format Device Drive/K/A Name/K/A OFS/FFS/SFS 
|----
|
| DIRCACHE/S NODIRCACHE/S NOICONS/S QUICK/S
|----
|Purpose:
| Initialises AROS disks (in System drawer)
|----
|Parameters:
|
;Device|Drive: Disk device or name to format
;Name: New volume name
;OFS: Old Filing System
;FFS: Fast File System
;Intl|International: FFS International mode
;NoIntl|NoInternational: International mode off
;SFS: Smart Filesystem
;DirCache|NoDirCache: Directory caching on or off,
;NoIcons: No disk or trash icons
;Quick: Less thorough format
|----
|Example:
| format drive dh0: name AROS 
Format Drive DH2: Name Docs SFS NOICONS QUICK
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Get
|----
|width=&quot;20%&quot;| Format:
| Get Name/A
|----
|Purpose:
| Returns contents of local env variable
|----
|Parameters:
|
;Name: Enviornment variable name
|----
|Example:
| Get RC
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Getenv
|----
|width=&quot;20%&quot;| Format:
| Getenv Name/A
|----
|Purpose:
| Return contents of a global environment variable
|----
|Parameters:
|
;Name: Enviornment variable name
|----
|Example:
| Getenv Wanderer
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Iconx
|----
|width=&quot;20%&quot;| Format:
| Iconx
|----
|Purpose:
| Enables a script to be run from Workbench. The script must have a Project .info file and
|----
|
| the Default Tool set to c:IconX to run it.
|----
|Example:
| Iconx
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |If
|----
|width=&quot;20%&quot;| Format:
| If NOT/S WARN/S ERROR/S FAIL/S EQ/K GT/K GE/K VAL/S EXISTS/K
|----
|Purpose:
| If condition is true execute following commands until an ELSE or ENDIF occurs.
|----
|Parameters:
| 
;Not: Reverse boolean result, 
;Warn: Test warn flag from previous command,
;Error: Test error flag from previous command, 
;Fail: Test fail flag from previous command,
;EQ:Equality test, 
;GT: Greater than test, 
;GE:Greater or equal test,
;VAL:Input is a number, 
;Exists: Test file exists.
|----
|Example:
| IF WARN, IF $count GT 10, IF EXISTS C:List
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Info
|----
|width=&quot;20%&quot;| Format:
| Info Device
|----
|Purpose:
| Displays information about disks
|----
|Parameters:
|
;Device: Name of device to display
|----
|Example:
| Info DH0:
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Install
|----
|width=&quot;20%&quot;| Format:
| Install Device/A NOBOOT/S CHECK/S FFS/S
|----
|Purpose:
| Saves a bootblock to a disk. If you have only one drive type INSTALL ? and
|----
|
| swap disks and then type DF0: and press RETURN to save bootblock.
|----
|Parameters:
|
;Device: Disk to install bootblock, 
;NoBoot: Erase bootblock, 
;Check: Test for bootblock,
|----
|
| FFS = Use Fast File System.
|----
|Example:
| Install DH0:
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |IPrefs
|----
|width=&quot;20%&quot;| Format:
| IPrefs
|----
|Purpose:
| Initialises preferences files on startup.
|----
|Example:
| IPrefs
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Join
|----
|width=&quot;20%&quot;| Format:
| Join File/M/A AS=TO/K/A
|----
|Purpose:
| Join two or files together.
|----
|Parameters:
|
;File: File(s) to join together, 
;To|as: Destination file
|----
|Example:
| Join File1 File2 File3 as FileFull
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Lab
|----
|width=&quot;20%&quot;| Format:
| Lab Label
|----
|Purpose:
| State a Label to Skip to in a script
|----
|Parameters:
|
;Label: Name of label
|----
|Example:
| Lab PROC2
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |List
|----
|width=&quot;20%&quot;| Format:
| List Dir/M P=PAT/K KEYS/S DATES/S NODATES/S To/K Sub/K Since/K Upto/K
|----
|
| QUICK/S BLOCK/S NOHEAD/S FILES/S DIRS/S LFORMAT/K ALL/S
|----
|Purpose:
| List file details in a directory.
|----
|Parameters:
| 
;Dir: One or more directory name(s)
;Keys: Display keys
;NoDates: Do not display dates
;To: Destination file
;Sub: Subdirectories included 
;Since: List files since date given
;Upto: List files upto given date 
;Quick: Simple directory list
;Block: List files in block sizes
;NoHead: Do not display header lines
;Files: Files only
;Dirs: Directorys only
;LFormat: Output list using this format string
;All: All files
|----
|Example:
| List Development: Block Dates Since=01-Jul-00
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Lock
|----
|width=&quot;20%&quot;| Format:
| Lock Drive/A ON/S OFF/S Passkey
|----
|Purpose:
| Lock a device from writing.
|----
|Parameters:
| 
;Drive: Drive to lock
;On|Off: Turn lock on or off
;PassKey: Specify password.
|----
|Example:
| Lock DH1: On GHK459
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |MakeDir
|----
|width=&quot;20%&quot;| Format:
| Makedir Name/M
|----
|Purpose:
| Create one or more new directories.
|----
|Parameters:
| 
;Name: One or more directories to create.
|----
|Example:
| MakeDir DH1:Docs DH1:Basic DH0:TempFiles
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |MakeLink
|----
|width=&quot;20%&quot;| Format:
| MakeLink From/A To/A HARD/S FORCE/S
|----
|Purpose:
| Creates a logical link between files
|----
|Parameters:
| 
;From: Link file
;To: Actual file
;Hard: Hard link
;Force: Link to sub-directory
|----
|Example:
| MakeLink T C:Type Hard
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Mount
|----
|width=&quot;20%&quot;| Format:
| Mount Device/M From/K
|----
|Purpose:
| Loads and mount a device
|----
|Parameters:
| 
;Device: Device to mount
;From: Mount file
|----
|Example:
| Mount DEVS:CD0
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |NewShell
|----
|width=&quot;20%&quot;| Format:
| NewShell Window From
|----
|Purpose:
| Open a new Shell console (CON) window
|----
|Parameters:
| 
;Window: Window config string
;From: Alternative script to Shell-Script.
|----
|Example:
| NewShell From S:Shell-Startup
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Path
|----
|width=&quot;20%&quot;| Format:
| Path Path/M ADD/S SHOW/S RESET/S REMOVE/S QUIET/S
|----
|Purpose:
| Set or change the program search path
|----
|Parameters:
| 
;Path: Directory path to change
;Add: Add path
;Show: Display path,
;Reset: Clear path
;Remove: Remove entry from path
;Quiet: No output
|----
|Example:
| Path SC:C Add
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Prompt
|----
|width=&quot;20%&quot;| Format:
| Prompt Prompt
|----
|Purpose:
| Change the prompt text (Codes: %R = last return code,
|----
|
| %S = Current path, %N = CLI Number)
|----
|Parameters:
| 
;Prompt: Path format
|----
|Example:
| Prompt &quot;%N.%S&amp;gt; &quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Protect
|----
|width=&quot;20%&quot;| Format:
| Protect File/A Flags ADD/S SUB/S ALL/S QUIET/S
|----
|Purpose:
| Change the 'rwedsp' flags of a file. (r=read,w=write, e=execute,d=delete,s=script,p=pure)
|----
|Parameters:
| 
;File: File to change
;Flags: One or more flags
;Add: Add flag(s) to existing flags
;Sub: Remove flags from file
;All: Change all files
;Quiet: No output
|----
|Example:
| Protect Editor rwed
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Quit
|----
|width=&quot;20%&quot;| Format:
| Quit RC/N
|----
|Purpose:
| Quit a script with optional return code
|----
|Parameters:
| 
;RC: Return Code
|----
|Example:
| Quit 5
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Relabel
|----
|width=&quot;20%&quot;| Format:
| Relabel Drive/A Name/A
|----
|Purpose:
| Change name of a disk
|----
|Parameters:
| 
;Drive: Disk to change
;Name: New volume name
|----
|Example:
| Relabel DH2: Documents
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Rename
|----
|width=&quot;20%&quot;| Format:
| Rename From/A/M To=As/A QUIET/S
|----
|Purpose:
| Rename or move one or more files
|----
|Parameters:
| 
;From: Old filename
;To|As: New filename
;Quiet: No output
|----
|Example:
| Rename MyDoc as MyDoc.doc
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |RequestChoice
|----
|width=&quot;20%&quot;| Format:
| RequestChoice  Title/A Body/A Gadgets/M PubScreen/K
|----
|Purpose:
| Asks for input via a requester
|----
|Parameters:
| 
;Title: Title for dialog box
;Body: Text for dialog box
;Gadgets: List of buttons
;Pubscreen: Screen to use
|----
|Example:
| RequestChoice &amp;gt;ENV:RT &quot;Format&quot; &quot;About to format your hard disk*nAre you sure?&quot; &quot;Go ahead&quot; &quot;No way!&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |RequestFile
|----
|width=&quot;20%&quot;| Format:
| RequestFile Drawer File/K Pattern/K Title/K Positive/K Negative/K AcceptPattern/K RejectPattern/K
|----
|
| SAVEMODE/S MULTISELECT/S DRAWERSONLY/S NOICONS/S PUBSCREEN/K
|----
|Parameters:
| 
;Drawer: Initial drawer to use, 
;File: Initial file name, 
;Pattern: Use pattern as filter,
;Title: Title of dialog box, 
;Positive: Text for OK button, 
;Negative: Text for Cancel button,
;AcceptPattern: Defines file pattern(s) to show (overrides Pattern),
;RejectPattern: Pattern(s) of files to hide,
;SaveMode: Change colours to indicate Save or other mode,
;MultiSelect: Allow multiple file selection, 
;DrawersOnly: Display only directories,
;NoIcons: Suppress info files, 
;PubScreen: Screen to use.
|----
|Purpose:
| Asks for a filename via ASL file requester
|----
|Example:
| RequestFile &amp;gt;ENV:File Title &quot;Select a File&quot; Positive &quot;Load&quot; Noicons
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Resident
|----
|width=&quot;20%&quot;| Format:
| Resident Name File REMOVE/S ADD/S REPLACE/S PURE=FORCE/S SYSTEM/S
|----
|Purpose:
| Stores AmigaDOS command in memory (quicker than reloading from disk each time it is executed).
|----
|
| To ensure a command can be made resident check the pure flag (see List).
|----
|Parameters:
| 
;Name|File: File to be made resident, 
;Remove: Remove file from resident list,
;Add: Add file to resident memory, 
;Pure|Force: Force a non-pure file to be resident,
;System: Show system's resident code segments.
|----
|Example:
| Resident C:Dir Pure
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
! colspan=&quot;2&quot; |Run
|----
|width=&quot;20%&quot;| Format:
| Run Command/F
|----
|Purpose:
| Execute a program in the background (multi-task)
|----
|Parameters:
| 
;Command: Program to run
|----
|Example:
| Run DirectoryOpus &amp;gt; NIL:
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Search
|----
|width=&quot;20%&quot;| Format:
| Search From/M Search/A ALL/S NONUM/S QUIET/S QUICK/S FILE/S PATTERN/S
|----
|Purpose:
| Search for a string in a file or a file on a disk
|----
|Parameters:
| 
;From: Directory to search from, 
;Search: Text to search for, 
;All: Search sub-directories,
;NoNum: Line numbers are not displayed, 
;Quiet: No Output, 
;Quick: Reduce output listing,
;File: Search a file rather than content, 
;Pattern: Search using a pattern.
|----
|Example:
| Search SYS: &quot;List&quot; File All
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Set
|----
|width=&quot;20%&quot;| Format:
| Set Name String/F
|----
|Purpose:
| Sets or lists a local environment variable (local to current shell or current process)
|----
|Parameters:
| 
;Name: Variable name, 
;String: Text or number for variable
|----
|Example:
| Set MyName &quot;Peter&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |SetClock
|----
|width=&quot;20%&quot;| Format:
| Setclock LOAD/S SAVE/S RESET/S
|----
|Purpose:
| Load or set the date and time from battery-backed clock
|----
|Parameters:
| 
;Load: Load date from clock 
;Save: Save date and time to clock 
;Reset: Resets the click
|----
|Example:
| Date 27-Nov-00 10:00, SetClock Save
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |SetDate
|----
|width=&quot;20%&quot;| Format:
| Setdate File/A Weekday Date Time ALL/S
|----
|Purpose:
| Set date of a file or directory (see List)
|----
|Parameters:
| 
;File: File to change, 
;Weekday: Day of week, 
;Date: Date, 
;Time: Time, 
;All: All files
|----
|Example:
| Setdate DEVS: Monday 10:30
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Setenv
|----
|width=&quot;20%&quot;| Format:
| Setenv Name String/F
|----
|Purpose:
| Change the contents of a environment variable
|----
|Parameters:
| 
;Name: Variable name 
;String: Text or number for variable
|----
|Example:
| Setenv Wanderer &quot;44&quot;
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |SetKeyboard
|----
|width=&quot;20%&quot;| Format:
| Setkeyboard Keymap/A
|----
|Purpose:
| Sets keyboard layout using layouts in Devs:Keymaps. You can use the Input preferences instead.
|----
|Parameters:
| 
;Keymap: Keymap file to use
|----
|Example:
| SetKeyboard USA0
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Skip
|----
|width=&quot;20%&quot;| Format:
| Skip Label BACK/S
|----
|Purpose:
| Jump to a label in a script (see Lab). Use back if label occurs before Skip command.
|----
|Parameters:
| 
;Label: Label name to skip to, 
;Back: Go back in script to label
|----
|Example:
| Skip Lab2 Back
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Sort
|----
|width=&quot;20%&quot;| Format:
| Sort From/A To/A Colstart/K CASE/S NUMERIC/S
|----
|Purpose:
| Sort a file and output to new file
|----
|Parameters:
| 
;From: File to sort, To = Output file, Colstart = Column to sort from,
|----
|
| 
;Case: Upper case entries are done first, 
;Numeric: Input treated as numbers.
|----
|Example:
| Sort Figures To SortedFigures Numeric
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Stack
|----
|width=&quot;20%&quot;| Format:
| Stack Size/N
|----
|Purpose:
| Change/display amount of stack space in bytes.
|----
|Parameters:
| 
;Size: Stack size in bytes
|----
|Example:
| Stack 1000000
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Status
|----
|width=&quot;20%&quot;| Format:
| Status Process/N FULL/S TCB/S CLI=ALL/S COM=COMMAND/K
|----
|Purpose:
| Display status of running programs. TCB is Task Control Block
|----
|Parameters:
| 
;Process: Task number 
;Full: Full output of process info
;TCB: Information except the command name 
;CLI|All: Command info only
;COM|Command: Search for command
|----
|Example:
| Status 2 Full
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Type
|----
|width=&quot;20%&quot;| Format:
| Type From/A/M TO/K OPT H|N/K HEX/S NUMBER/S
|----
|Purpose:
| Display contents of text file on screen and binary files using HEX with optional line numbers.
|----
|Parameters:
| 
;From: Text file to display
;To: Output file or device
;Opt H | Hex: Display as hex values
;Opt N | Number: Number the lines.
|----
|Example:
| Type C:DIR HEX
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Unset
|----
|width=&quot;20%&quot;| Format:
| Unset Name
|----
|Purpose:
| Remove a local env variable
|----
|Parameters:
| 
;Name: Environment variable name
|----
|Example:
| Unset MyName
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Unsetenv
|----
|width=&quot;20%&quot;| Format:
| Unsetenv Name
|----
|Purpose:
| Remove a global env variable
|----
|Parameters:
| 
;Name: Environment variable name
|----
|Example:
| Unsetenv Wanderer
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Unalias
|----
|width=&quot;20%&quot;| Format:
| Unalias Name
|----
|Purpose:
| Remove a short name for a command
|----
|Parameters:
| 
;Name: Alias name
|----
|Example:
| UnAlias MyDir
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Version
|----
|width=&quot;20%&quot;| Format:
| Version Name Version/N Revision/N FILE/S FULL/S Unit/N INTERNAL/S RES/S
|----
|Purpose:
| Display workbench, library or device version information.
|----
|Parameters:
| 
;Name:  File
;Version: Print Kickstart or Workbench number and sets env variables and sets Warn flag
;Revision: As Version but for Revision numer, File = Check file rather than memory
|----
|
| 
;Full: Display full information, 
;Internal: Check internal files, 
;Res: Check resident files.
|----
|Example:
| Version kickstart Version=39 Revision=106
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Wait
|----
|width=&quot;20%&quot;| Format:
| Wait Time/N SEC=SECS/S MIN=MINS/S UNTIL/K
|----
|Purpose:
| Wait for a specified period of time
|----
|Parameters:
| 
;Time: Time period in either Sec (Seconds) or Mins (Minutes) 
;Until: Wait until a time
|----
|Example:
| Wait Until 12:00
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Which
|----
|width=&quot;20%&quot;| Format:
| Which File/A NORES/S RES/S ALL/S
|----
|Purpose:
| Find where a file is in command path (see Path) and sets Warn flag.
|----
|Parameters:
| 
;File: File to locate
;NoRes: Resident list is not searched
;Res: Only the resident list is searched
;All: Search full path
|----
|Example:
| Which Multiview
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot; |Why
|----
|width=&quot;20%&quot;| Format:
| Why
|----
|Purpose:
| Display reason why a previous command failed
|----
|Example:
| Why
|----
|}

===Additional DOS commands===


&lt;pre&gt;
DMS
Format:
 DMS Read file[.DMS] [FROM dev:] [TEXT filetext] [CMODE mode] [LOW lowtrack] [HIGH hightrack] [NOVAL] [NOZERO] [ENCRYPT password]
 DMS Write file[.DMS],,, [TO dev:] [LOW lowtrack] [HIGH hightrack] [NOVAL] [NOTEXT] [NOPAUSE [DECRYPT password]
 DMS Repack file[.DMS] [TO dev:] [LOW lowtrack] [HIGH hightrack] [CMODE mode]
 DMS View file[.DMS],,, [FULL] DMS Text file[.DMS],,,
 DMS Test file[.DMS],,, DMS Help
Purpose:  To read, write or view Disk Masher disk images of floppy disks.
Example: DMS Write MyDisk.DMS FROM DF0:

Installer
Format:  Installer [SCRIPT] filename &lt;[APPNAME] name&gt; &lt;[MINIUSER] level&gt; &lt;[DEFUSER] default&gt; &lt;[LOGFILE] 
 logname&gt; &lt;[LANGUAGE] language&gt; &lt;NOPRETEND&gt; &lt;NOLOG&gt; &lt;NOPRINT&gt;
Purpose: To install an application via a installer script. Usually provided as a default tool for script 
 files in icon.
Example: Installer SCRIPT InstallApp APPNAME MyProgram LOGFILE DH0:MyProgram.log

LHA
Format:  LHA [-options] &lt;command&gt; &lt;archive[.LZH|LHA]&gt; [[homedir] &lt;filespec...] [@file] [destination]
Purpose: To create, modify or list LHA or LZH files
Examples:
LHA a pictures.lha #?.jpg (archives all jpg files into pictures.lha)
LHA l pictures.lha        (lists all files in pictures.lha)
LHA x pictures.lha        (extracts all files from pictures.lha)

LZX
Format:  LZX [-options] &lt;command&gt; &lt;archive&gt; [&lt;file&gt; ...] [&lt;destdir&gt;]
Purpose: To create, modify or list LZX archive files.
Examples:
LZX a documents.lzx #?.doc (archives all doc files into documents.lzx)
LZX l documents.lzx        (lists all files in documents.lzx)
LZX x documents.lzx        (extracts all files from documents.lzx)
&lt;/pre&gt;


===Additional DOS Information===

&lt;pre&gt;
Clear Screen
Example: Echo &quot;*E[0;0H*E[J&quot;
Purpose: Clears the screen. Uses printer commands to control text formatting in CLI, so *E is equivalent to ESC character.The command clear is normally defined using an Alias or an AmigaDOS script in S: folder.

Text in Italics
Example: Echo &quot;*E[3mItalics*E[23m&quot;
Purpose: *E[3m turns on italics and *E[23m turns off italics

Text in Bold
Example: Echo &quot;*E[1mBold*E[22m&quot;
Purpose: *E[1m turns on bold, and *E[22m turns off bold.

Underline Text
Example: Echo &quot;*E[4mUnderline*E[24m&quot;
Purpose: *E[4m turns on underline, and *E24m turns off underline.

Coloured Text
Example: Echo &quot;*E[32mRed Text*E[0m&quot;
Purpose: *E[nm where n=30-39 for foreground color or n=40-49 for background colour.
*E[0m resets to normal character set.
&lt;/pre&gt;

Seems that Amiga shell allows an escape sequence to begin with just the 0x9B character, OR it allows the more traditional 0x1B character (033 in octal) followed the [ character. For sake of clarity, I will represent it by the C string \033[

AROS does not understand the \033[0m sequence, therefore you need to reset it using another colour sequence (on the assumption that the user has not changed the default Shell colours). This turns out to be \033[31;40m . It makes sense to play it safe, and follow it by the (ignored on AROS) \033[0m sequence.

Therefore my final highlight code looks like this:
 printf(&quot;Before\033[32;43mDuring\033[31;40m\033[0mAfter\n&quot;);

Or if you code in E (like me) then it is this:
 PrintF('Before\e[32;43mDuring\e[31;40m\e[0mAfter\n')


==Escape Codes==

&lt;pre&gt;
07 Bell - Flash screen and sound bell
08 Backspace - move cursor back one position
09 vertical tab - move cursor up one line
10 line feed - move cursor down one line
11 is not listed in my book
12 form feed - clear screen
13 Carriage return - move cursor to start of line
14 Set MSB of each character. (Print extended chars)
15 Clear MSB of each character.
*e[c - Clear window and turn all modes off
*e[0m - All modes turned off
*e[1m - Bold text enabled
*e[3m - Italic enable
*e[4m - Uderline
*e[7m - Inverted text enable
*e[8m - text becomes invisible (grey on grey)
*e[3xm - Text colour becomes colour x (0-7)
*e[4xm - Background colour becomes colour x (0-7)
*e[n@ - Insert n spaces at cursor position.
*e[nA - Cursor up n lines. Default 1
*e[nB - Cursor down n lines. Default 1
*e[nC - Cursor forward n characters. Default 1
*e[nD - Cursor back n characters. Default 1
*e[nE - Cursor next n lines(to column 1). Default 1
*e[nH - Cursor to row n (Y position)
*e[;nH - Cursor to column n (X position)
*e[y;xH - Cursor to position X,Y
*e[J - Erase from cursor to end of display
*e[K - Erase from cursor to end of line
*e[I - Insert line above line at cursor
*e[M - Delete line at cursor
*e[nS - Scroll up n lines
*e[nT - Scroll down n lines
*e[nt - set page length to n lines (in current font)
*e[nu - Set line length in characters of current font
*e[nx - Set left offset in characters
*e[ny - Set top offset in lines
*e[0 p - Disable cursor: Note space between zero and p
*e[ p - Enable cursor. Note space
&lt;/pre&gt;


Example of coloured text in the shell 

&lt;pre &gt;
prompt &quot;*E[&gt;1m*E[1;37;41m%n.%s&gt; *E[0;32;41m&quot;
echo &quot;*E[0;0H*E[J&quot; 
&lt;/pre &gt; 

&lt;pre &gt; 
*E[&gt;1m
&lt;/pre &gt; 
Is a so called SGR command that omits the first few parameters. It turns BOLD ON.

&lt;pre &gt; 
*E[1;37;41m%n.%s&gt; 
&lt;/pre &gt; 
SGR command that tells:
- boldface (1)
- foregroundcolor 7 (37).
Which means it is using pencolor #7 (which is black by default on aros, hence the setpencolor command).
- use background color 1 (41).
Which means it is using pencolor #1 (which is black by default on aros).
- %n means printing the current opened cli/shell-number
- %s means printing the current path
- &gt; print a nice pipe token after all the above (and also a space-character).

&lt;pre &gt; 
*E[0;32;41m
&lt;/pre &gt; 
SGR command that tells:
- plain text (0)
- foregroundcolor 2 (32).
Which means it is using pencolor #2 (which is white by default on aros).
- backgroundcolor 1 (41).
Which means it is using pencolor #1 (which is black by default on aros).

&lt;pre &gt; 
*E[0;0H
&lt;/pre &gt; 
command 'Cursor position'
- set row to 0 (0)
- set column to 0 (0)
Please note that this does not seem to work on AROS as on classic (not checked). it seems that the lowest nr for AROS to use is 1 (for both left and top).

&lt;pre &gt; 
*E[J
&lt;/pre &gt; 
command 'erase in display' (no additional parameters used in this command).

&lt;pre&gt;
;Set MagicWB colors in AROS
setpencolor SCREEN=&quot;Workbench&quot; PEN=0 COLOR=$959595
setpencolor SCREEN=&quot;Workbench&quot; PEN=3 COLOR=$A2673B
setpencolor SCREEN=&quot;Workbench&quot; PEN=4 COLOR=$7B7B7B
setpencolor SCREEN=&quot;Workbench&quot; PEN=5 COLOR=$AFAFAF
setpencolor SCREEN=&quot;Workbench&quot; PEN=6 COLOR=$7C90AA
setpencolor SCREEN=&quot;Workbench&quot; PEN=7 COLOR=$97A9FF
&lt;/pre&gt;


===DOS commands only present in AROS===
{| class=&quot;wikitable&quot;
!colspan=&quot;2&quot;|AddAudioModes
|----
|width=&quot;20%&quot;| Format:
|
|----
|Purpose:
|
|----
|Parameters:
| Files/M Quiet/S Refresh/S Remove/S DblScan/S
|----
|Example:
|
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|Beep
|----
|width=&quot;20%&quot;| Format:
|
|----
|Purpose:
|
|----
|Parameters:
|
|----
|Example:
|
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|CheckMem
|----
|width=&quot;20%&quot;| Format:
|
|----
|Purpose:
|
|----
|Parameters:
|
|----
|Example:
|
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|Delay
|----
|width=&quot;20%&quot;| Format:
|
|----
|Purpose:
|
|----
|Parameters:
| Time/N Tick=Ticks/S
|----
|Example:
|
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|DevList
|----
|width=&quot;20%&quot;| Format:
| DevList
|----
|Purpose:
| gives a list of devices running - address, version, revision, opencnt, flags, name
|----
|Parameters:
|
|----
|Example:
| devlist
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|LibList
|----
|width=&quot;20%&quot;| Format:
| LibList
|----
|Purpose:
| gives address, version, revision, opencnt, flags, name of open libraries and mui
|----
|Parameters:
|
|----
|Example:
| liblist
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|Reboot
|----
|width=&quot;20%&quot;| Format:
| Reboot
|----
|Purpose:
| warm reboots machine - not functioning
|----
|Parameters:
|
|----
|Example:
|
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|ResList
|----
|width=&quot;20%&quot;| Format:
| reslist
|----
|Purpose:
| gives a list of resources - name and address
|----
|Parameters:
|
|----
|Example:
| reslist
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|Shutdown
|----
|width=&quot;20%&quot;| Format:
| shutdown
|----
|Purpose:
| power off computer
|----
|Parameters:
|
|----
|Example:
| not functioning
|----
|}


{| class=&quot;wikitable&quot; width=&quot;90%&quot;
!colspan=&quot;2&quot;|TaskList
|----
|width=&quot;20%&quot;| Format:
| tasklist
|----
|Purpose:
| gives a list of tasks running - address, type, priority, state, cpu, time, stack, used, name
|----
|Parameters:
|
|----
|Example:
| tasklist
|----
|}


==Examples==


{{BookCat}}</text>
      <sha1>b9am5r63m2xuv8qruzqc76dva7g8so2</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/User/Applications</title>
    <ns>0</ns>
    <id>237399</id>
    <revision>
      <id>4669845</id>
      <parentid>4669746</parentid>
      <timestamp>2026-09-13T07:33:46Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669845</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="240390" sha1="0xt9ri5q5d9p9dt65isf8h12ojyq1bw" xml:space="preserve">
==Introduction==


[[#Graphical Image Editing Art]]
[[#Office Application]]
[[#Audio]]

[[#Misc Application]]
[[#Games &amp; Emulation]]

[[#Application Guides]]

[[#top|...to the top]]


[[#top|...to the top]]

Most apps can be opened on the Workbench (aka publicscreen pubscreen) which is the default display option but can offer a custom one set to your configurations (aka custom screen mode promotion). These custom ones tend to stack so the possible use of A-M/A-N method of switching between full screens and the ability to pull down screens as well 

If you are interested in creating or porting new software, see [http://en.wikibooks.org/wiki/Aros/Developer/Docs here]

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Internet Applications 
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Web Online Browser [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=network/browser/ Amelinium], Odyssey 2.0, [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1175&amp;highlight=odyssey&amp;rowstart=100 Odyssey 3.0], [], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/comm/www Amelinium], [https://blog.alb42.de/programs/amifox/ amifox] with [https://github.com/alb42/wrp wrp server], IBrowse*, Voyager*, [https://github.com/amigazen/aweb3/ AWeb 3.6 src], [https://github.com/matjam/aweb AWeb Src], [http://aminet.net/package/comm/www/NetSurf-m68k-sources Netsurf], [], 
|&lt;!--AmigaOS4--&gt;[ Odyssey OWB], [ Timberwolf (Firefox port 2011)], [http://amigaworld.net/modules/newbb/viewtopic.php?forum=32&amp;topic_id=32847 OWB-mui], [http://strohmayer.org/owb/ OWB-Reaction], IBrowse*, [http://os4depot.net/index.php?function=showfile&amp;file=network/browser/aweb.lha AWeb], Voyager, [http://www.os4depot.net/index.php?function=browse&amp;cat=network/browser Netsurf], 
|&lt;!--MorphOS--&gt;Wayfarer, [http://fabportnawak.free.fr/owb/ Odyssey OWB], [ Netsurf], IBrowse*, AWeb, [], 
|-
|&lt;!--Sub Menu--&gt;YouTube, Dailymotion website downloading videos audio [https://github.com/yt-dlp/yt-dlp yt-dlp], [https://clipgrab.org/ clipgrab],  
|&lt;!--AROS--&gt;[], [https://blog.alb42.de/amitube/ Amitube], 
|&lt;!--Amiga OS--&gt;[https://blog.alb42.de/amitube/ Amitube], [ smtube], 
|&lt;!--AmigaOS4--&gt;[https://blog.alb42.de/amitube/ Amitube], getVideo, Tubexx, [https://github.com/walkero-gr/aiostreams aiostreams], 
|&lt;!--MorphOS--&gt;[ ytsearch], [https://blog.alb42.de/amitube/ Amitube], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 getVideo], Tubexx 
|-
|&lt;!--Sub Menu--&gt;Old style E-mailing SMTP POP3 IMAP based 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/email SimpleMail], [http://sourceforge.net/projects/simplemail/files/ src], [https://github.com/jens-maus/yam YAM] 
|&lt;!--Amiga OS--&gt;[http://sourceforge.net/projects/simplemail/files/ SimpleMail], [https://github.com/jens-maus/yam YAM]
|&lt;!--AmigaOS4--&gt;SimpleMail, YAM, 
|&lt;!--MorphOS--&gt; SimpleMail, YAM
|-
|&lt;!--Sub Menu--&gt;IRC, ICB, 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat WookieChat], [https://sourceforge.net/projects/wookiechat/ Wookiechat src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat AiRcOS], Jabberwocky, 
|&lt;!--Amiga OS--&gt;Wookiechat, AmIRC 
|&lt;!--AmigaOS4--&gt;Wookiechat 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=5 Wookiechat], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 AmIRC], 
|-
|&lt;!--Sub Menu--&gt;Instant Messaging IM like [https://github.com/BlitterStudio/amidon Hollywood lang based Mastodon client], BlueSky AT protocol, Facebook(TM), Twitter X (TM), Bitlbee IRC Gateway and others 
|&lt;!--AROS--&gt;[https://github.com/kaffeine1/telegram-amiga telegram-amiga], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat jabberwocky], 
|&lt;!--Amiga OS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], CLIMM, SabreMSN, jabberwocky, 
|&lt;!--AmigaOS4--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], SabreMSN,
|&lt;!--MorphOS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 PolyglotNG], SabreMSN,
|-
|&lt;!--Sub Menu--&gt;Torrents 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/p2p ArTorr], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;CTorrent, Transmission 
|&lt;!--MorphOS--&gt;MLDonkey, Beehive, [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Transmission], CTorrent, 
|-
|&lt;!--Sub Menu--&gt;FTP 
|&lt;!--AROS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], MarranoFTP, 
|&lt;!--Amiga OS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://aminet.net/package/comm/tcp/AmiFTP AmiFTP], AmiTradeCenter, ncFTP, 
|&lt;!--AmigaOS4--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|&lt;!--MorphOS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Pftp], [http://aminet.net/package/comm/tcp/AmiFTP-1.935-OS4 AmiFTP], 
|-
|&lt;!--Sub Menu--&gt;WYSIWYG Web Site Editor
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Internet Radio Streaming Audio [http://www.gnu.org/software/gnump3d/ gnump3d], [http://www.icecast.org/ Icecast2] Server (Broadcast) and Client (Listen), [ mpd], [http://darkice.sourceforge.net/ DarkIce], [http://www.dyne.org/software/muse/ Muse], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc], Mplayer (Icecast Client only), 
|&lt;!--Amiga OS--&gt;[https://github.com/sandlbn/TuneFinder TuneFinder C Src], [https://github.com/sandlbn/TuneFinderMUI TuneFinderMUI], [http://amigazeux.net/anr/ AmiNetRadio], [], [], 
|&lt;!--AmigaOS4--&gt;[http://www.tunenet.co.uk/ Tunenet], 
|&lt;!--MorphOS--&gt;Mplayer, AmiNetRadio, 
|-
|&lt;!--Sub Menu--&gt;VoIP (Voice over IP) with SIP Client (Session Initiation Protocol) or Asterisk IAX2 Clients Softphone (skype like) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;AmiPhone with Speak Freely, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Weather Forecast 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ WeatherBar], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench AWeather], []
|&lt;!--Amiga OS--&gt;[http://amigazeux.net/wetter/ Wetter], [https://github.com/emartisoft/AmiWeatherForecasts AmiWeatherForecasts src], 
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/?function=showfile&amp;file=utility/workbench/flipclock.lha FlipClock], 
|&lt;!--MorphOS--&gt;[http://amigazeux.net/wetter/ Wetter], 
|-
|&lt;!--Sub Menu--&gt;Street Road Maps Route Planning GPS Tracking  
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/muimapparium/ MuiMapparium] [https://build.alb42.de/ Build of MuiMapp versions], 
|&lt;!--Amiga OS--&gt;AmiAtlas*, UKRoutePlus*, [http://blog.alb42.de/ AmOSM], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://blog.alb42.de/programs/mapparium/ Mapparium], 
|-
|&lt;!--Sub Menu--&gt;Clock and Date setting from the internet (either ntp or websites) [https://www.timeanddate.com/worldclock/ World Clock], [http://www.time.gov/ NIST], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc ntpsync],  
|&lt;!--Amiga OS--&gt;ntpsync 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Newsgroups
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[http://newscoaster.sourceforge.net/ Newscoaster], [https://github.com/jens-maus/newsrog NewsRog], [ WorldNews], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;RSS 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/Team-Boingo/AmiRSS AmiRSS src]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;AI
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/murinsel/AmigaAI Claude], [https://github.com/geekychris/amiga_mcp AI on host machine], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BBS
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Graphical Image Editing Art==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Image Editing
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Pixel Raster Artwork [https://github.com/LibreSprite/LibreSprite LibreSprite based on GPL aseprite], [https://github.com/abetusk/hsvhero hsvhero], [], 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/ZunePaint/ ZunePaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit LunaPaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit GrafX2], [ LodePaint needs OpenGL], 
|&lt;!--Amiga OS--&gt;[http://www.amigaforever.com/classic/download.html PPaint], GrafX2, [https://github.com/grovdata/Amiga_Sources/blob/master/software.md DeluxePaint], [http://www.amiforce.de/perfectpaint/perfectpaint.php PerfectPaint], Zoetrope, Brilliance2*, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit LodePaint], GrafX2, 
|&lt;!--MorphOS--&gt;Sketch, Pixel*, GrafX2, [http://morphos.lukysoft.cz/en/vypis.php?kat=3 LunaPaint]
|-
|&lt;!--Sub Menu--&gt;Image viewing 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LookHere], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LoView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer PicShow] , [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--Amiga OS--&gt;PicShow, PicView, Photoalbum,
|&lt;!--AmigaOS4--&gt;WarpView, PicShow, flPhoto, Thumbs, [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album]
|-
|&lt;!--Sub Menu--&gt;Photography retouching / Image Manipulation like Photoshop(tm)  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOEffects], 
|&lt;!--Amiga OS--&gt;[ Tecsoft Video Paint aka TVPaint], Photogenics*, ArtEffect*, ImageFX*, XiPaint, fxPaint, ImageMasterRT, Opalpaint, 
|&lt;!--AmigaOS4--&gt;WarpView, flPhoto, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit Photocrop]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], ImageFX*, 
|-
|&lt;!--Sub Menu--&gt;Manage RAW picture folder galleries like Darktable, RAWtherapy, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Graphic Format Converter - ICC profile support sRGB, Adobe RGB, XYZ and linear RGB 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;GraphicsConverter, ImageStudio, [http://www.coplabs.org/artpro.html ArtPro]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Thumbnail Generator [], 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/shell Thumbnail Generator]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Icon Editor
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/iconedit Archives], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench Icon Toolbox], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/iconedit IconEditor]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Pixel Art Animation 
|&lt;!--AROS--&gt;Lunapaint
|&lt;!--Amiga OS--&gt;PPaint, AnimatED, Scala*, GoldDisk MovieSetter*, Walt Disney's Animation Studio*, ProDAD*, [https://github.com/historicalsource/DeluxePaint DeluxePaint src], Brilliance
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 Titler] 
|-
|&lt;!--Sub Menu--&gt;2D SVG based MovieSetter type 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;MovieSetter*, Fantavision*
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Morphing 
|&lt;!--AROS--&gt;[ GLMorph]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Cad (qcad-&gt;LibreCAD, etc.) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Xcad, MaxonCAD
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Cad like FreeCad, BRL-CAD, OpenSCAD, AvoCADo, etc. using dxf, obj (vertices), blend, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;XCad3d*, DynaCADD*, Cycas, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Model Rendering of glft (json) gbl (png jpg), usdz (USD files with materials, textures, and animations), FBX Filmbox is a proprietary Autodesk format, 
|&lt;!--AROS--&gt;POV-Ray
|&lt;!--Amiga OS--&gt;[http://www.discreetfx.com./amigaproducts.html CINEMA 4D]*, POV-Ray, Lightwave3D*, Real3D*, Caligari24*, Reflections/Monzoom*, [https://github.com/privatosan/RayStorm Raystorm src], Tornado 3D
|&lt;!--AmigaOS4--&gt;Blender, POV-Ray, Yafray
|&lt;!--MorphOS--&gt;Blender, POV-Ray, Yafray
|-
|&lt;!--Sub Menu--&gt;3D Format Converter [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=graphics/convert/ 3doc.i386-aros], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=showfile&amp;file=graphics/convert/ivcon.lha IVCon]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen grabbing display 
|&lt;!--AROS--&gt;[ Screengrabber], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc snapit], [http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record screen recorder], []
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Grab graphics music from apps [https://github.com/Malvineous/ripper6 ripper6], [],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Office Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Office
!width:10%;|AROS (x86)
!width:10%;|[http://en.wikipedia.org/wiki/Amiga_software Commodore-Amiga OS 3.1] (68k)
!width:10%;|[http://en.wikipedia.org/wiki/AmigaOS_4 Hyperion OS4] (PPC)
!width:10%;|[http://en.wikipedia.org/wiki/MorphOS MorphOS] (PPC)
|-
|&lt;!--Sub Menu--&gt;Office Suite 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[ Softwood Final Office], [ Wordworth Office], [ Digita Office],  [ The Works!], [ Europress Mini Office], [], [ Papyrus Office Demo], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Word-processing 
|&lt;!--AROS--&gt;[https://finalwriter.godaddysites.com/ Final Writer 7*], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1995&amp;rowstart=20&amp;pid=12668#post_12668 Slovo], [https://github.com/sodero/MUI-Vim/releases MUI-Vim], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/wordprocessing Cinnamon Writer], [], 
|&lt;!--AmigaOS--&gt;[ Softwood FinalCopy II*], Haage AmigaWriter*, Digita WordWorth*, Softwood FinalWriter*, Micro-Systems Excellence 3*, Arnor Protext, Rashumon, [ InterWord], [ KindWords], [WordPerfect], [ New Horizons Flow], [ CygnusEd Pro], [ Micro-systems Scribble], 
|&lt;!--AmigaOS4--&gt;AbiWord, [ CinnamonWriter], 
|&lt;!--MorphOS--&gt;[ Cinnamon Writer], [http://www.meta-morphos.org/viewtopic.php?topic=1246&amp;forum=53 scriba], [http://morphos.lukysoft.cz/en/index.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Spreadsheets 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/leu/ Leu], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/spreadsheet ], 
|&lt;!--AmigaOS--&gt;[https://aminet.net/package/biz/spread/ignition-src Ignition Src 1.3], [MaxiPlan 500 Plus], [OXXI Plan/IT v2.0 Speadsheet], [ Superplan], [ Creative Developments TurboCalc], [ ProCalc], [ InterSpread], [Digita DGCalc], [ Gold Disk Advantage], [ Micro-systems Analyze!]
|&lt;!--AmigaOS4--&gt;Gnumeric, [https://ignition-amiga.sourceforge.net/ Ignition], 
|&lt;!--MorphOS--&gt;[ ignition], [http://morphos.lukysoft.cz/en/vypis.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Presentations
|&lt;!--AROS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, 
|&lt;!--Amiga OS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, MediaPoint, PointRider, Scala*, 
|&lt;!--Amiga OS4--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider 
|&lt;!--MorphOS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider
|-
|&lt;!--Sub Menu--&gt;Databases 
|&lt;!--AROS--&gt;[http://sdb.freeforums.org/ SDB], [http://archives.arosworld.org/index.php?function=browse&amp;cat=office/database BeeBase], 
|&lt;!--Amiga OS--&gt;Precision Superbase 4 Pro*, Arnor Prodata*, BeeBase, Datastore, FinalData*, AmigaBase, Fiasco, Twist2*, [Digita DGBase], [], 
|&lt;!--AmigaOS4--&gt;BeeBase, SQLite, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=6 BeeBase], 
|-
|&lt;!--Sub Menu--&gt;PDF Viewing and editing digital signatures 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/arospdf/ ArosPDF via splash], [https://github.com/wattoc/AROS-vpdf vpdf wip], 
|&lt;!--Amiga OS--&gt;APDF 
|&lt;!--AmigaOS4--&gt;AmiPDF 
|&lt;!--MorphOS--&gt;APDF, vPDF, 
|-
|&lt;!--Sub Menu--&gt;Note Taking markdown support like Obsidian like, joplin, OneNote, EverNotes, xournalpp, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Study and analyse, collect, organize, annotate, cite, and share
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PIM Personal Information Manager - Day Diary Planner Calendar App 
|&lt;!--AROS--&gt;[ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;Digita Organiser*, On The Ball, Everyday Organiser, [ Contact Manager], 
|&lt;!--AmigaOS4--&gt;AOrganiser, 
|&lt;!--MorphOS--&gt;[http://polymere.free.fr/orga_en.html PolyOrga], 
|-
|&lt;!--Sub Menu--&gt;Accounting
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=office/misc ETB], LoanCalc, [ ], [ ], [ ], 
|[ Digita Home Accounts2], Accountant, Small Business Accounts, Account Master, [ Amigabok], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Project Management Research 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;SuperGantt, SuperPlan, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Desktop 
|&lt;!--AROS--&gt;Wanderer, Scalos, Workbook, DOpus5, 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://github.com/zapek/Ambient Ambient Src]
|-
|&lt;!--Sub Menu--&gt;System Wide Search 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool Finder], [], [], 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Wide Dictionary - multilingual [http://sourceforge.net/projects/babiloo/ Babiloo], [http://code.google.com/p/stardict-3/ StarDict], 
|&lt;!--AROS--&gt;[ ],  
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System wide Thesaurus - multi lingual
|&lt;!--AROS--&gt;[ ], 
|Kuma K-Roget*, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Sticky Desktop Notes (post it type) 
|&lt;!--AROS--&gt;[http://aminet.net/package/util/wb/amimemos.i386-aros AmiMemos], [https://aminet.net/package/util/wb/amimemos.src-aros AmiMemos Src], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/util/wb/StickIt-2.00 StickIt v2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DTP Desktop Publishing 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOPublisher], 
|&lt;!--Amiga OS--&gt;[http://pagestream.org/ Pagestream]*, Professional Pro Page*, Saxon Publisher, Pagesetter, PenPal, 
|&lt;!--AmigaOS4--&gt;[http://pagestream.org/ Pagestream]* 
|&lt;!--MorphOS--&gt;[http://pagestream.org/ Pagestream]* 
|-
|&lt;!--Sub Menu--&gt;Printing 
|&lt;!--AROS--&gt;Postscript 3 laser printers, [https://github.com/bohunamiga/MintPRINT MintPRINT AirPrint IPP], [ Ghostscript], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/boingball/MintPRINT MintPRINT IPP], [https://github.com/Andiweli/AmiAirprint AmiAirprint], [http://www.irseesoft.de/tp_what.htm TurboPrint]*, [ GutenPrint], [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], [], [], 
|&lt;!--AmigaOS4--&gt;(some native drivers), 
|&lt;!--MorphOS--&gt;early TurboPrint included, [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], 
|-
|&lt;!--Sub Menu--&gt;Scanning 
|&lt;!--AROS--&gt;[ SCANdal], [], 
|&lt;!--Amiga OS--&gt;FxScan*, ScanQuix* 
|&lt;!--AmigaOS4--&gt;SCANdal (Sane)
|&lt;!--MorphOS--&gt;SCANdal
|-
|&lt;!--Sub Menu--&gt;OCR
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/convert gOCR] 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos-files.net/categories/office/text Tesseract] 
|-
|&lt;!--Sub Menu--&gt;Text Editing
|&lt;!--AROS--&gt;Jano Editor (already installed as Editor), [http://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit EdiSyn], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Vim], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd] [https://github.com/vidarh/FrexxEd src], [ NoWinEd], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/text/edit/TurboText20 TurboText20 ttx], Annotate, MicroGoldED/CubicIDE*, CygnusED*, Protext*, NoWinED, 
|&lt;!--AmigaOS4--&gt;Notepad, Annotate, CygnusED*, NoWinED, 
|&lt;!--MorphOS--&gt;MorphOS ED, NoWinED, GoldED/CubicIDE*, CygnusED*, Annotate, 
|-
|&lt;!--Sub Menu--&gt;Office Fonts [http://sourceforge.net/projects/fontforge/files/fontforge-source/ Font Designer] 
|&lt;!--AROS--&gt;[ ], [ ], 
|&lt;!--Amiga OS--&gt;TypeSmith*, SaxonScript (GetFont Adobe Type 1), 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Drawing Vector
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/amifig/ ZuneFIG previously AmiFIG], [https://github.com/serk118/designworks-aros designworks aros 64bit]
|&lt;!--Amiga OS--&gt;Drawstudio*, ProVector*, ArtExpression*, Professional Draw*, AmiFIG, MetaView, [https://gitlab.com/amigasourcecodepreservation/designworks Design Works Src], [], 
|&lt;!--AmigaOS4--&gt;MindSpace, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit amifig], 
|&lt;!--MorphOS--&gt;SteamDraw, [http://aminet.net/package/gfx/edit/amifig amiFIG], 
|-
|&lt;!--Sub Menu--&gt;video conferencing (jitsi) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;source code hosting
|&lt;!--AROS--&gt;Gitlab, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (server)
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/VNC_Server ArosVNCServer], 
|&lt;!--Amiga OS--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC], [http://dspach.free.fr/amiga/avnc/index.html AVNC]
|&lt;!--AmigaOS4--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC] 
|MorphVNC, vncserver
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (client) login and connect to another machine 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/VNC_Client/ ArosVNC], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc rdesktop], 
|&lt;!--Amiga OS--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://dspach.free.fr/amiga/vva/index.html VVA], [http://www.hd-zone.com/ RDesktop]
|&lt;!--AmigaOS4--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|-
|&lt;!--Sub Menu--&gt;notifications 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Ranchero 
|&lt;!--AmigaOS4--&gt;Ringhio 
|&lt;!--MorphOS--&gt;MagicBeacon 
|-
|&lt;!--Sub Menu--&gt;Biometric facial logins and fingerprint security features 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Audio==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Audio
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing playback Audio like MP3, [https://github.com/chrg127/gmplayer NSF], [https://github.com/kode54/lazyusf miniusf .usflib] [https://gitlab.com/kode54/psflib with pfslib], [], [], etc 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ HarmonyPlayer hp], [http://www.a500.org/downloads/audio/index.xhtml playcdda] CDs, [ WildMidi Player], [https://bszili.morphos.me/ UADE mod player], [], [ RNOTunes], [ mp3Player], [], 
|&lt;!--Amiga OS--&gt;AmiNetRadio, AmigaAmp, playOGG, [https://codeberg.org/tygre/amimodradio amimodradio]
|&lt;!--AmigaOS4--&gt;TuneNet, SimplePlay, AmigaAmp, TKPlayer
|AmiNetRadio, Mplayer, Kaya, AmigaAmp
|-
|&lt;!--Sub Menu--&gt;Editing Audio 
|&lt;!--AROS--&gt;[ Audio Evolution 4] 
|&lt;!--Amiga OS--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec Src], [http://www.sonicpulse.de/eng/news.html SoundFX], [ Samplitude], 
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec], AmiSoundED, [http://os4depot.net/?function=showfile&amp;file=audio/record/audioevolution4.lha Audio Evolution 4] 
|[http://www.hd-rec.de/HD-Rec/index.php?site=home HD-Rec], 
|-
|&lt;!--Sub Menu--&gt;Editing Tracker Music
|&lt;!--AROS--&gt;[https://github.com/hitchhikr/protrekkr Protrekkr], [ Schism Tracker], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/tracker MilkyTracker], [http://www.hivelytracker.com/ HivelyTracker], [ Radium in AROS already],  [http://www.a500.org/downloads/development/index.xhtml libMikMod], 
|&lt;!--Amiga OS--&gt;MilkyTracker, HivelyTracker, DigiBooster, Octamed SoundStudio, [https://github.com/elindstrom/soundtracker soundtracker], 
|&lt;!--AmigaOS4--&gt;MilkyTracker, HivelyTracker, GoatTracker
|MilkyTracker, GoatTracker, DigiBooster, 
|-
|&lt;!--Sub Menu--&gt;Editing Music [], [https://github.com/kmatheussen/camd CAMD] and/or staves and musical notes on manuscript 
|&lt;!--AROS--&gt;[http://bnp.hansfaust.de/ Bars and Pipes], [], [], 
|&lt;!--Amiga OS--&gt;[http://bnp.hansfaust.de/ Bars'n'Pipes], MusicX* David &quot;Talin&quot; Joiner &amp; Craig Weeks (for Notator-X), Deluxe Music Construction Set DMCS2*, [https://github.com/timoinutilis/midi-sequencer-amigaos Horny c Src] [https://github.com/kas1e/midi-sequencer-amigaos/tree/master/HornyGCC HornyGCC OS4 src] [https://github.com/capehill/midi-sequencer-amigaos Horny OS4 fork src] [https://www.amigans.net/modules/newbb/viewtopic.php?start=0&amp;topic_id=8143&amp;order=ASC&amp;status=&amp;mode=0 OS4 thread], HD-Rec, [https://aminet.net/package/mus/midi/dominatorV1_51 Dominator], [https://github.com/royaltm/Amiga-midiIn Amiga-midiIn]
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Rockbeat, [http://bnp.hansfaust.de/download.html Bars'n'Pipes], [https://github.com/gooofy/freeaction Horny OS4 src fork], Audio Evolution 4, 
|&lt;!--MorphOS--&gt;Bars'n'Pipes, 
|-
|&lt;!--Sub Menu--&gt;Sound Sampling 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/record Audio Evolution 4], [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;did=162 Quick Record], [https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc SOX to get AIFF 16bit files], [https://github.com/aros-development-team/AROS/tree/master/workbench/tools/AHIRecord AHIRecord], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/mus/edit/AudioEvolution3_src Audio Evolution 3 c src], [ Samplitude]*, Audiomaster IV*, 
|&lt;!--AmigaOS4--&gt;[https://github.com/timoinutilis/phonolith-amigaos phonolith c src], HD-Rec, Audio Evolution 4,
|&lt;!--MorphOS--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Audio Evolution 4,
|-
|&lt;!--Sub Menu--&gt;Audio Processing like easyeffects so having limiter, compressor, convolver, equalizer and auto volume and many other plugins 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Live Looping or Audio Misc - Groovebox like
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;CD/DVD burn
|[https://code.google.com/p/amiga-fryingpan/ FryingPan], 
|&lt;!--Amiga OS--&gt;FryingPan, [http://www.estamos.de/makecd/#CurrentVersion MakeCD], 
|&lt;!--AmigaOS4--&gt;FryingPan, AmiDVD, 
|[http://www.amiga.org/forums/printthread.php?t=58736 FryingPan], Jalopeano, 
|-
|&lt;!--Sub Menu--&gt;CD/DVD audio rip
|Lame, [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;cfid=0&amp;did=167 Quick CDrip],
|&lt;!--Amiga OS--&gt;Lame,  
|&lt;!--AmigaOS4--&gt;Lame, 
|Lame,  
|-
|&lt;!--Sub Menu--&gt;MP3 v1 and v2 Tagger
|&lt;!--AROS--&gt;id3ren (v1), [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/edit mp3info], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|
|-
|&lt;!--Sub Menu--&gt;Audio Convert
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc Sox], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/mus/misc/SoundBox SoundBox], [http://aminet.net/package/mus/misc/SoundBoxKey SoundBox Key], [http://aminet.net/package/mus/edit/SampleE SampleE], sox 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DJ mixing jamming 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/djh0ffman/PT1210 Hoffman PT1210 DJ tracker], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Radio Automation Software [http://www.rivendellaudio.org/ Rivendell], [http://code.campware.org/projects/livesupport/report/3 Campware LiveSupport], [http://www.sourcefabric.org/en/airtime/ SourceFabric AirTime], [http://www.ohloh.net/p/mediabox404 MediaBox404], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speakers Audio Sonos Mains AC networked wired controlled 
*2005 ZP100 with ZP80 
*2008 Zoneplayer ZP120 (multi-room wireless amp)  ZP90 receiver only with CR100 controller, 
*2009 ZonePlayer S5, 
*2010 BR100 wireless Bridge (no support),   
*2011 Play:3
*2013 Bridge (no support), Play:1,  
*2016 Arc,   Play:1,   
*Beam (Gen 2),   Playbar,  Ray,   Era 100,   Era 300,   Roam,   Move 2,   
*Sub (Gen 3),   Sub Mini,  Five,  Amp  S2 
|&lt;!--AROS--&gt;SonosController 
|&lt;!--Amiga OS--&gt;SonosController
|&lt;!--AmigaOS4--&gt;SonosController
|&lt;!--MorphOS--&gt;SonosController
|-
|&lt;!--Sub Menu--&gt;Smart Speakers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Video Creativity and Production==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Video
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing Video 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ VAMP], [http://www.a500.org/downloads/video/index.xhtml CDXL player], [http://www.a500.org/downloads/video/index.xhtml IffAnimPlay], [], 
|&lt;!--Amiga OS--&gt;Frogger*, AMP2, MPlayer, RiVA*, MooViD*, 
|&lt;!--AmigaOS4--&gt;DvPlayer, MPlayer 
|&lt;!--MorphOS--&gt;MPlayer, Frogger, AMP2, VLC 
|-
|&lt;!--Sub Menu--&gt;Streaming Video and game streaming like OBS studio, Parsec, [https://github.com/lizardbyte/sunshine sunshine], [https://github.com/moonlight-stream/moonlight-qt moonlight], etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Playing DVD 
|&lt;!--AROS--&gt;[http://a-mc.biz/ AMC]*, Mplayer 
|&lt;!--Amiga OS--&gt;AMP2, Frogger 
|&lt;!--AmigaOS4--&gt;[http://a-mc.biz/ AMC]*, DvPlayer*, AMP2,  
|&lt;!--MorphOS--&gt;Mplayer 
|-
|&lt;!--Sub Menu--&gt;Screen Recording
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record Screenrecorder], [ ], [ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Screenrecorder, 
|-
|&lt;!--Sub Menu--&gt;Create Edit Individual Video - Amiga like OSs have no pro NLE 
|&lt;!--AROS--&gt;[ Mencoder], [ Quick Videos], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit AVIbuild], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc FrameBuild], FFMPEG, 
|&lt;!--Amiga OS--&gt;[ MainConcept Mainactor Broadcast*], [http://en.wikipedia.org/wiki/Video_Toaster Video Toaster*], MacroSystem MovieShop 4.3*, proDAD Adorage*, [ IOSpirit VHI studio]*, [Gold Disk ShowMaker], [], 
|&lt;!--AmigaOS4--&gt;FFMpeg/GUI 
|&lt;!--MorphOS--&gt;Blender, Mencoder, FFmpeg
|-
|&lt;!--Sub Menu--&gt;Subtitle editor 
|&lt;!--AROS--&gt;[https://aminet.net/package/text/edit/Slarti_Arosx86ABIv0 Slarti_Arosx86ABIv0], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;IP-based video production workflows with High Dynamic Range (HDR), 10-bit color collaborative NDI, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Blogging like Lemmy or kbin
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR face recognition for Vtubers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting Live2D models with Cubism type editor or [https://github.com/AyagamiDev/ayagami ayagami] like with zipped moc3 with model metadata (model3, cdi3) 
&lt;pre&gt;
Model data (cmo3)
Basic motions (can3)
Background image (png)
Set of files for embedding (runtime folder)
• Model data (moc3)
• Motion data (motion3.json)
• Model settings file (model3.json)
• Physics settings file (physics3.json)
• Display auxiliary file (cdi3.json)
&lt;/pre&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting chatters .VRML models - standardized 3D file format for VR avatars 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;V-tubers V-tubing like Vseeface with Openseeface tracker or Vpuppr (virtual puppet project) for online live 2d / 3d art models rigging rigged LIV 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]


==Misc Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;File Management 
|&lt;!--AROS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 DOpus Magellan aka DOpus 5], [ Scalos], [ ], 
|&lt;!--Amiga OS--&gt;DOpus2, DOpus 4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], ClassAction, FileMaster, [http://www.amiga.org/forums/showthread.php?t=4897 DirWork 2]*, [https://github.com/RudolphRiedel/DiskMaster2 DiskMaster2 src], 
|&lt;!--AmigaOS4--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], Filer, AmiDisk 
|&lt;!--MorphOS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|-
|&lt;!--Sub Menu--&gt;File Verification / Repair 
|&lt;!--AROS--&gt;[https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility md5sum], [https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility/filetool asum], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool workpar2] (PAR2),  [http://zakalwe.fi/~shd/foss/cksfv/files/ compile cksfv from website], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Par2, 
|-
|Application Installer 
|&lt;!--AROS--&gt;[], [ InstallerNG], 
|&lt;!--Amiga OS--&gt;InstallerNG, Grunch, 
|&lt;!--AmigaOS4--&gt;Jack
|&lt;!--MorphOS--&gt;Jack 
|-
|&lt;!--Sub Menu--&gt;Compression archiver [https://github.com/FS-make-simple/paq9a paq9a], [], 
|&lt;!--AROS--&gt;XAD system is a toolkit designed for handling various file and disk archiver
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[https://aminet.net/package/util/pack/decrunchmania_os4 Crunchmania CrM2 depacker], 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Binary Hexadecimal Editor 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Zaphod], [],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Partition Editor formatter Disk Management
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1440&amp;highlight=partition&amp;pid=8821#post_8821 QuickPart], [ HDToolBox]
|&lt;!--Amiga OS--&gt;[https://github.com/stefanskotte/hdpart hdpart], [https://github.com/ChuckyGang/AmiPart AmiPart], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Repair and backups 
|&lt;!--AROS--&gt;ArSFSDoctor, 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/disk/bakup/quarterback_src Quarterback Tools C and asm src], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Disk check, integrity and history [https://github.com/smartmontools/smartmontools smart tools], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Multiple File renaming
|&lt;!--AROS--&gt;DOpus 4 or 5, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Anti Virus
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;VChecker, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Random Wallpaper Desktop changer [ DOpus5], [ Scalos],  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Alarm Clock, Timer, Stopwatch, Countdown 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench DClock], [http://aminet.net/util/time/AlarmClockAROS.lha AlarmClock], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 2==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;C/C++ IDE Integrated Development 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/aidea/ AIDEa], [ Murks], [],  
|&lt;!--Amiga OS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, [ StormC], [https://github.com/jens-maus/amide amide], [], 
|&lt;!--AmigaOS4--&gt;CodeBench , [https://gitlab.com/boemann/codecraft CodeCraft], 
|&lt;!--MorphOS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, 
|-
|&lt;!--Sub Menu--&gt;C/C++ Text Editors 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd], [https://github.com/vidarh/FrexxEd FrexxEd src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate] with [https://www.onyxsoft.se/files/annotate_src.lha src], 
|&lt;!--Amiga OS--&gt;[ Protext], [ CED], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://www.onyxsoft.se/annotate.html Annotate], 
|-
|&lt;!--Sub Menu--&gt;Repository
|&lt;!--AROS--&gt;[ Git]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;Git
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BASIC Computer Language 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Basic4SDL], [ Ace Basic], [ X-AMOS], [SDLBasic], [ Alvyn], 
|&lt;!--Amiga OS--&gt;[http://www.amiforce.de/main.php Amiblitz 3] with [https://github.com/AmiBlitz/AmiBlitz3 Asm src], [http://amos.condor.serverpro3.com/AmosProManual/contents/c1.html Amos Pro] with [https://github.com/AmiDARK/AmosProfessionalUnity-Official-Releases Asm src], [http://aminet.net/package/dev/basic/ace24dist ACE Basic], [https://github.com/gooofy/aqb aqb], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;sdlBasic
|-
|&lt;!--Sub Menu--&gt;Computer Languages Translation [https://tetracorp.github.io/guide/reverse-engineering-amiga.html], [https://amigasourcecodepreservation.gitlab.io/amiga-assembler-insider-guide/], [https://github.com/kermitfrog/Amiga-Re-Engineering Rust, Ghidra and FS-UAE], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://bitbucket.org/rhinoid/convert68000toc/src/main/ convert m68k seka asm-one to c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Gui Creators
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/guitool MuiBuilder], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ MuiBuilder],  
|-
|&lt;!--Sub Menu--&gt;Catalog .cd .ct Custom App Language Editors 
|&lt;!--AROS--&gt;FlexCat, [https://archives.arosworld.org/index.php?function=browse&amp;cat=utility Flexcat GUI], [], 
|&lt;!--Amiga OS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|&lt;!--AmigaOS4--&gt;[http://aminet.net/package/dev/misc/simplecat SimpleCat], FlexCat
|&lt;!--MorphOS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|-
|&lt;!--Sub Menu--&gt;Cross Development 
|&lt;!--AROS--&gt;[], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/geekychris/amiga_mcp amiga_mcp], [https://github.com/mbergmann-sh/AmigaED4-IDE AmigaED4-IDE], [https://lemonspawn.com/turbo-rascal-syntax-error-expected-but-begin/ Turbo Rascal], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Misc Application 3==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;System 
|&lt;!--AROS--&gt;[ SysExplorer], [ SysMon], [ Scout], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Terminals Shells CLIs 
|&lt;!--AROS--&gt;[https://tomaszstaniak.com/aros-term/ aros-term], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;OSK On Screen Keyboard
|&lt;!--AROS--&gt;[], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/util/wb/OSK.lha OSK]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Magnifier Magnifying Glass Magnification 
|&lt;!--AROS--&gt;[http://www.onyxsoft.se/files/zoomit.lha ZoomIT], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Comic Book CBR CBZ format reader viewer 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comics], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comicon], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Reader 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#legadon Legadon EPUB],[]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Converter 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Text to Speech tts [https://github.com/JonathanFly/bark-installer Bark], [], 
|&lt;!--AROS--&gt;[ Echo &quot; &quot; &gt;SPEAK:A1 inbuilt], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc flite], 
|&lt;!--Amiga OS--&gt;[http://www.text2speech.com translator], [https://github.com/sidick/narrator.wyoming narrator.wyoming], [], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=search&amp;tool=simple FLite]
|&lt;!--MorphOS--&gt;[http://se.aminet.net/pub/aminet/mus/misc/ FLite]
|-
|&lt;!--Sub Menu--&gt;Speech Voice Recognition Dictation - [http://sourceforge.net/projects/cmusphinx/files/ CMU Sphinx], [http://julius.sourceforge.jp/en_index.php?q=en/index.html Julius], [http://www.isip.piconepress.com/projects/speech/index.html ISIP], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speech Voice Changer [], [], [], [], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Display Blanker screensaver 
|&lt;!--AROS--&gt;Blanker Commodity (built in), [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/screenblanker GarshneBlanker], [http://sourceforge.net/projects/gblanker/ GBlanker Src], [], 
|&lt;!--Amiga OS--&gt;MultiCX, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;ModernArt Blanker, 
|-
|&lt;!--Sub Menu--&gt;Fortune Cookie Quotes Sayings 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc AFortune], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 4==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Fractals mandelbrot, etc 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc], 
|&lt;!--Amiga OS--&gt;ZoneXplorer, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Landscape Rendering 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/raytrace WCS World Construction Set], 
|&lt;!--Amiga OS--&gt;[ Vista Pro], [http://en.wikipedia.org/wiki/World_Construction_Set World Construction Set]
|&lt;!--AmigaOS4--&gt;[ WCS World Construction Set],
|&lt;!--MorphOS--&gt;[ WCS World Construction Set],
|-
|&lt;!--Sub Menu--&gt;Astronomy [https://sourceforge.net/projects/skychart/ skychart freepascal], [], [], 
|&lt;!--AROS--&gt;[ Digital Almanac (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/search?query=planetarium Aminet search], [http://aminet.net/misc/sci/DA3V56ISO.zip Digital Almanac], [https://aminet.net/package/misc/sci/da3sourceV58 Src c V58], [ Galileo renamed to Distant Suns]*, [], 
|&lt;!--AmigaOS4--&gt;[http://sourceforge.net/projects/digital-almanac/ Digital Almanac], Distant Suns*, [http://www.digitaluniverse.org.uk/ Digital Universe]*,
|&lt;!--MorphOS--&gt;[http://www.aminet.net/misc/sci/da3.lha Digital Almanac], [http://www.aminet.net/package/misc/sci/da3-mos-src Src c V56], 
|-
|&lt;!--Sub Menu--&gt;Astrology [https://sourceforge.net/projects/skylendar/ skylendar], [https://github.com/CruiserOne/Astrolog Astrolog], [https://www.astrolog.org/astrolog/astfile.htm Astrology alt site], [https://saravali.github.io/download.html Maitreya], [https://github.com/alamahant/Asteria Asteria], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Genealogy History Family Tree Ancestry Records (FreeBMD, FreeREG, and FreeCEN file formats or GEDCOM GenTree)
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; [ Origins], [ Your Family Tree], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Languages 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Fun School, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;https://github.com/evil4dmin/ami2ha
|-
|&lt;!--Sub Menu--&gt;Mathematics ([http://www-fourier.ujf-grenoble.fr/~parisse/install_en.html Xcas], etc.), 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/scientific mathX] 
|&lt;!--Amiga OS--&gt;Maple V, mathX, Fun School, GCSE Maths, [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;Yacas 
|&lt;!--MorphOS--&gt;Yacas 
|-
|&lt;!--Sub Menu--&gt;Maths Graph Function Plotting
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#MUIPlot MUIPlot], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;App Utility Launcher Dock toolbar  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/docky BoingBar], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/adkennan/DockBot Dockbot],
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Printer [https://github.com/OrcaSlicer/OrcaSlicer OrcaSlicer]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PCB design
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Digital Signage
|&lt;!--AROS--&gt;Hollywood, Hollywood Designer 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;HAM radio, amateur radio, packet radio,  [], [], [], [https://cemaxecuter.com/ Dragon OS], [https://github.com/km4ack/73Linux with 73 link update], [https://www.youtube.com/watch?v=YAL5KNePRSg video for], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/punktniklas/NiKom NiKom], [https://www.amigarealm.com/amiga/amicomms/comm4.htm Comm4], [https://www.amigarealm.com/archives/comms/aarug/ TNC Terminal Node Controller with packets over serial connections on Yaesu or Woxum handheld], [https://aminet.net/comm/misc AmiCom], [ with 7Plus file encoder/decoder], [ mksstv], [ RTTYam], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;modern smart-home network like Home Assistant, Mosquitto, EMQX,  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/evil4dmin/ami2ha HA], [https://github.com/sidick/midge mtqq.lib], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Teaching classroom learning training [https://github.com/moodle/moodle moodle], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Games &amp; Emulation==

Some emulators/games require OpenGL to function and to adjust ahi prefs channels, frequency and unit0 and unit1 and 
[http://aros.sourceforge.net/documentation/users/shell/changetaskpri.php changetaskpri -1]

Rom patching  https://www.marcrobledo.com/RomPatcher.js/ https://www.romhacking.net/patch/ (ips, ups, bps, etc) and this other site supports the latter formats https://hack64.net/tools/patcher.php 

Free public domain roms for use with emulators can be found [http://www.pdroms.de/ here] as most of the rest are covered by copyright rules. If you like to read about old games see [http://retrogamingtimes.com/ here] and [http://www.armchairarcade.com/neo/ here] and a [http://www.vintagecomputing.com/ blog] about old computers. Possibly some of the [http://www.answers.com/topic/list-of-best-selling-computer-and-video-games best selling] of all time. [http://en.wikipedia.org/wiki/List_of_computer_system_emulators Wiki] with emulated systems list.

[https://archive.gamehistory.org/ Archive of VGHF], [https://library.gamehistory.org/ Video Game History Foundation Library search]


{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Emulation]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Games Emulation Amstrad CPC 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [ Caprice32 (OpenGL &amp; pure SDL)], [ Arnold], [https://retroshowcase.gr/cpcbox-master/], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Apple2 and 2GS
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Arcade 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Mame], [ SI Emu (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;Mame, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem xmame], amiarcadia, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 Mame], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 2600 [], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Stella], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 5200 [https://github.com/wavemotion-dave/A5200DS A5200DS], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 7800
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 400 800 130XL [https://github.com/wavemotion-dave/A8DS A8DS], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Atari800], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Lynx
|&lt;!--AROS--&gt;[http://myfreefilehosting.com/f/6366e11bdf_1.93MB Handy (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Jaguar
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Bandai Wonderswan 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation BBC Micro and Acorn Electron [http://beehttps://bem-unix.bbcmicro.com/download.html BeebEm], [http://b-em.bbcmicro.com/ B-Em], [http://elkulator.acornelectron.co.uk/ Elkulator], [http://electrem.emuunlim.com/ ElectrEm], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Dragon 32 and Tandy CoCo [http://www.6809.org.uk/xroar/ xroar], [], 
|&lt;!--AROS--&gt;[], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C16 Plus4
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C64
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Vice (ABIv0 only)], [], 
|&lt;!--Amiga OS--&gt;Frodo, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem viceplus], 
|&lt;!--MorphOS--&gt;Vice, 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore Amiga
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Janus UAE], Emumiga, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer UAE], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 UAE], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Japanese MSX MSX2 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Intelivision
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Colecovision and Adam
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Milton Bradley (MB) Vectrex [ Vectrex OpenGL], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation PICO8 Pico-8 fantasy video game console [https://github.com/egordorichev/pemsa-sdl/ pemsa-sdl], [https://github.com/jtothebell/fake-08 fake-08], [https://github.com/Epicpkmn11/fake-08/tree/wip fake-08 fork], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo Gameboy
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem vba no sound], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem vba]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo NES
|&lt;!--AROS--&gt;[ EmiNES], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Fceu], [https://github.com/takahirox/nes-js?tab=readme-ov-file nes-js], [https://github.com/bfirsh/jsnes jsnes], [https://github.com/angelo-wf/NesJs NesJs], 
|&lt;!--Amiga OS--&gt;AmiNES, [http://www.dridus.com/~nyef/darcnes/ darcNES], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem amines]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo SNES
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Zsnes], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem warpsnes]
|&lt;!--MorphOS--&gt;[http://fabportnawak.free.fr/snes/ Snes9x], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo N64 
*HLE and plugins [ mupen64], [https://github.com/ares-emulator/ares ares], [https://github.com/N64Recomp/N64Recomp N64Recomp], [https://github.com/rt64/rt64 rt64], [https://github.com/simple64/simple64 Simple64], 
*LLE [], 
|&lt;!--AROS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+],
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+], [http://aminet.net/package/misc/emu/tr-981125_src TR64], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Gamecube Wii]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Wii U]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/yuzu-emu Nintendo Switch]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation NEC PC Engine 
|&lt;!--AROS--&gt;[], [], [https://github.com/yhzmr442/jspce js-pce], 
|[http://www.hugo.fr.fm/ Hugo], [http://mednafen.sourceforge.net/ Mednafen], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem tgemu]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Master System (SMS)
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Dega], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem sms], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem osmose]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Genesis/Megadrive
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem gp no sound], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem DGen], 
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/genplus-gx/ Genplus], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem genesisplus]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Saturn 
*HLE [https://mednafen.github.io/ mednafen], [http://yabause.org/ yabause], [], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;[http://yabause.org/ Yabause], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Dreamcast 
*HLE [https://github.com/flyinghead/flycast  flycast], [https://code.google.com/archive/p/nulldc/downloads NullDC], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair ZX80 and ZX81 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair Spectrum 
|[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Fuse (crackly sound)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer SimCoupe], [ FBZX slow], [https://jsspeccy.zxdemo.org/ jsspeccy], [http://torinak.com/qaop/games qaop], 
|&lt;!--Amiga OS--&gt;[http://www.lasernet.plus.com/ Asp], [http://www.zophar.net/sinclair.html Speculator], [http://www.worldofspectrum.org/x128/index.html X128], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair QL
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/QDOS4amiga1 QDOS4amiga]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation SNK NeoGeo Pocket
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem gngeo], NeoPop, 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sony PlayStation
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem FPSE], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem FPSE]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS2]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS3]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://vita3k.org/ Sony Vita]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/shadps4-emu/shadPS4 PS4]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation [http://en.wikipedia.org/wiki/Tangerine_Computer_Systems Tangerine] Oric and Atmos 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Oricutron]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem Oricutron]
|&lt;!--MorphOS--&gt;[http://aminet.net/package/misc/emu/oricutron Oricutron]
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 99/4 99/4A [https://github.com/wavemotion-dave/DS994a DS994a], [], [https://js99er.net/#/ js99er], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/TI4Amiga TI4Amiga], [http://aminet.net/package/misc/emu/TI4Amiga_src TI4Amiga src in c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation HP 38G 40GS 48 49G/50G Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 58 83 84 85 86 - 89 92 Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [https://www.rockpapershotgun.com/ General]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|- style=&quot;background:lightgrey;{{text default color}}; text-align:center; font-weight:bold;&quot;
| Games [https://www.trackawesomelist.com/michelpereira/awesome-open-source-games/ Open Source and others] || AROS || Amiga OS || Amiga OS4 || Morphos 
|-
|&lt;!--Sub Menu--&gt;Games Action like [https://github.com/opentomb/OpenTomb opentomb], [https://github.com/LostArtefacts/TRX TRX formerly Tomb1Main], [https://github.com/TombEngine TombEngine], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Thrust], [https://github.com/fragglet/sdl-sopwith sdl sopwith], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action BOH], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/BSzili/OpenLara/tree/amiga/src source of openlara SDL2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Adventure like [http://dotg.sourceforge.net/ DMJ], [https://github.com/kromenak/gengine Gabriel Knight 3], [http://www.sarien.net/ Sierra Sarien], [https://github.com/klembot/twinejs twine js], [https://github.com/QSPFoundation/qspgui Quest Soft Player QSP], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/adventure dmagnetic], [https://archives.arosworld.org/?function=browse&amp;cat=emulation/misc ScummVM], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying frotz infocom], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Board like [https://github.com/aperture-software/colditz-escape escape from colditz], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/board], [http://amigan.1emu.net/releases Africa]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Cards 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/card], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12934#post_12934 Balatro], 
|&lt;!--AmigaOS--&gt;[http://home.arcor.de/amigasolitaire/e/welcome.html Reko], [https://github.com/samskivert/beschei-en beschei Src], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Misc [https://github.com/michelpereira/awesome-open-source-games Awesome open], [https://github.com/bobeff/open-source-games General Open Source], [https://github.com/SAT-R/sa2 Sonic Advance 2], [https://github.com/velorek1/cwordle Wordle type], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games FPS like [https://aminet.net/package/game/shoot/D1X_Rebirth_AGA Descent D1X src], [https://github.com/DescentDevelopers/Descent3 Descent 3], [https://github.com/Fewnity/Counter-Strike-Nintendo-DS Counter-Strike-Nintendo-DS], [https://github.com/Aleph-One-Marathon/alephone Bungie Marathon 1994], [https://zdoom.org/downloads UzDoom opengl 3.3], [https://github.com/ZDoom/gzdoom gzdoom opengl 3+], [https://zdoom.org/downloads LZDoom opengl 2.1], 
|&lt;!--AROS--&gt;Doom, Quake, [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Quake 3 Arena (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Assault Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube 2 Sauerbraten (OpenGL)], [http://fodquake.net/test/ FodQuake QuakeWorld], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Duke Nukem 3D], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Darkplaces Nexuiz Xonotic], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Doom 3 SDL (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Hexenworld and Hexen 2], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Aliens vs Predator Gold 2000 avp (openGL)], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Odamex (openGL doom)], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ zgloom], [], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ ab3dhd], [], 
|&lt;!--Amiga OS--&gt;Doom, Quake, AB3D, Fears, Breathless, Gloom, 
|&lt;!--AmigaOS4--&gt;Doom, Quake, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12 Doom], Quake, Quake 3 Arena, [https://github.com/OpenXRay/xray-16 S.T.A.L.K.E.R Xray]
|-
|&lt;!--Sub Menu--&gt;Games MMORG like 
|&lt;!--AROS--&gt;[ Eternal Lands (OpenGL)],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Platform like 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform], [ Maze of Galious], [ Gish]*(openGL), [ Mega Mario], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ thextech SMBX], [http://www.gianas-return.de/ Giana's Return], [http://www.sqrxz.de/ Sqrxz], [www.sqrxz2.de/ Sqrxz 2], [http://www.sqrxz.de/sqrxz-3/ Sqrxz 3], [http://www.sqrxz.de/sqrxz-4/ Sqrxz 4], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform Cave Story], [https://bszili.morphos.me/ Frogatto], [https://bszili.morphos.me/ OpenJazz], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ pekkakana2], [ Aquaria], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ sonic CD], [], 
|&lt;!--Amiga OS--&gt;[ Giana Sisters], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Puzzle [https://github.com/mariopartyrd/marioparty4/tree/port Party], [https://github.com/mdodis/OpenSolomonsKey OpenSolomonsKey], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle], [ Cubosphere (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle Candy Crisis], [http://bszili.morphos.me/ TailTale], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Racing [ Trigger Rally], [ VDrift], [http://www.ultimatestunts.nl/index.php?page=2&amp;lang=en Ultimate Stunts], [http://maniadrive.raydium.org/ Mania Drive], [https://github.com/plowteam/donut Simpsons Hit and Run], [], 
|&lt;!--AROS--&gt;[ Super Tux Kart (OpenGL)], [http://www.dusabledanslherbe.eu/AROSPage/F1Spirit.30.html F1 Spirit (OpenGL)], [http://bszili.morphos.me/index.html MultiRacer], [https://bszili.morphos.me/ Speed Dreams], [https://archives.arosworld.org/?function=showfile&amp;file=game/driving/dethrace-0.10.1.x86_64-aros-v11.zip Carmageddon dethrace 64bit], [], 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://bszili.morphos.me/index.html Speed Dreams], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12], [http://bszili.morphos.me/index.html TORCS], 
|-
|&lt;!--Sub Menu--&gt;Games 1st first person DRPG [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/OpenEnroth/OpenEnroth OpenEnroth MM], []
|&lt;!--AROS--&gt;[https://github.com/BSzili/aros-stuff Arx Libertatis], [http://www.playfuljs.com/a-first-person-engine-in-265-lines/ js raycaster], [https://github.com/Dorthu/es6-crpg webgl], [https://github.com/sonountaleban/AmiShockolate System Shock], [], [], 
|&lt;!--AmigaOS--&gt;Phantasie, Faery Tale, Dungeon Master, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 3rd third person action CRPG  [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/alexbatalov/fallout1-ce fallout ce], [https://github.com/rwengine/openrw gta3], [https://github.com/gta-reversed/gta-reversed gta3 sa], [https://github.com/mrxenginner/reVC gta3 vc revc], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ fheroes2 homm2], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ breakhack], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ devilutionx diablo 1 hellfire], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ fallout 1], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ stratagus], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ hostile-takeover], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games isometric RPG [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/topics/dungeon?l=javascript Dungeon], [], [https://github.com/clintbellanger/heroine-dusk JS Dusk], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying nethack], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying GemRB], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games card based RPG [https://github.com/open-duelyst/duelyst Duelyst], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games turn based tactics RPG [], [], [], [], [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy UFO AI], [http://play.freeciv.org/ FreeCiv], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Strategy [http://rtsgus.org/ RTSgus], [http://stargus.sourceforge.net/ Stargus], [https://github.com/KD-lab-Open-Source/Perimeter Perimeter], [https://matty77.itch.io/conflict-3049 conflict-3049], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy MegaGlest (OpenGL)], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ signus], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=140&amp;pid=12446#post_12446 Wargus warcraft 2 setup], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Rhythm, Beat, Step [], [], [https://clonehero.net/ clonehero], [https://github.com/MatteoGodzilla/Dj-Engine Dj-Engine], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc Frets on Fire], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Shoot Em Ups [http://www.mhgames.org/oldies/formido/ Formido], [http://code.google.com/p/violetland/ Violetland], 
||&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Open Tyrian], [http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ Alien Blaster], [https://github.com/OpenFodder/openfodder OpenFodder], [https://archives.arosworld.org/?function=showfile&amp;file=game/action/ tbftss The Battle for the Solar System: the Pandora War]
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ The Battle for the Solar System: the Pandora War]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Simulations [http://scp.indiegames.us/ Freespace 2], [http://www.heptargon.de/gl-117/gl-117.html GL117], [http://code.google.com/p/corsix-th/ Theme Hospital], [http://code.google.com/p/freerct/ Rollercoaster Tycoon], [http://hedgewars.org/ Hedgewars], [https://github.com/raceintospace/raceintospace raceintospace], [https://github.com/Return-To-The-Roots RTTR Settlers 2], [https://github.com/OoliteProject/oolite oolite elite], [https://github.com/fesh0r/newkind newkind elite], [https://github.com/bohemiainteractive/cwr Arma Cold War Src], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;SimCity, SimAnt, Sim Hospital, Theme Park, [https://github.com/angree/openttd_amiga_68k openttd amiga_68k], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Life Sim [https://github.com/ACreTeam/forest Animal Crossing], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Horror [https://github.com/Mikompilation/MikuPan Fatal Frame], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Sandbox Voxel Open World Exploration [https://github.com/ClassiCube/ Classicube],[http://www.michaelfogleman.com/craft/ Craft], [https://github.com/tothpaul/DelphiCraft DelphiCraft],[https://www.minetest.net/ Luanti formerly Minetest], [ infiniminer], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Battle Royale [https://bruh.io/ Play.Bruh.io], [https://www.coolmathgames.com/0-copter Copter Royale], [https://surviv.io/ Surviv.io], [https://nuggetroyale.io/#Ketchup Nugget Royale], [https://miniroyale2.io/ Miniroyale2.io], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Tower Defense [https://chriscourses.github.io/tower-defense/ HTML5], [https://github.com/SBardak/Tower-Defense-Game TD C++], [https://github.com/bdoms/love_defense LUA and LOVE], [https://github.com/HyOsori/Osori-WebGame HTML5], [https://github.com/PascalCorpsman/ConfigTD ConfigTD Pascal], [https://github.com/GloriousEggroll/wine-ge-custom Wine], []
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12871#post_12871 Plants vs Zombies PvZ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Visual Novel Engines [https://github.com/diane1f0cd/VisualNovelTemplate Visual Novel Template], [https://github.com/Kirilllive/tuesday-js Tuesday JS], [https://github.com/tejasnayak25/vnsutra vnsutra], [https://github.com/weetabix-su/renpsp-dev RenPSP], [https://github.com/Galladite27/ONScripter-EN ONScripter-EN], [https://github.com/NathanGuilhot/VNES-Raylib https://github.com/NathanGuilhot/VNES VNES in Raylib], [https://www.renpy.org/latest.html renpy ren'py python based], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Reality VR [https://gitlab.com/madsbuvi/openmw openmw vr], [https://github.com/Team-Beef-Studios/BeefRaiderXR BeefRaiderXR], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Table Top VTT [ Roll20], [https://www.owlbear.rodeo/ owlbear rodeo], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Computer assisted TableTop TTRPG OSR [https://www.rpgsolo.com/play.php RPGSolo], [https://github.com/fpsvogel/solo-ttrpgs Solo TTRPG], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 2D 3D Engines [https://github.com/fegennari/3DWorld 3DWorld], [https://github.com/GarageGames/Torque3D Torque3D], [https://github.com/gameplay3d/GamePlay GamePlay 3D],  [https://www.babylonjs.com/ BabylonJS ], [ Godot], [ Ogre], [ Crystal Space], [https://github.com/JacobHess03/ Dragon-Quest like], [https://github.com/bjornbytes/lovr Lua LOVE for 2D LOVR for 3D], [], 
|&lt;!--AROS--&gt;[https://www.arkhamdev.net/wiki.htm?id=agx Arkham Development antiryadgx 8.9 lts with register], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/alpyre/Sevgi_Engine Sevgi Engine], [], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games C based game frameworks [https://github.com/orangeduck/Corange Corange], [https://github.com/scottcgi/Mojoc Mojoc], [https://orx-project.org/ Orx], [https://github.com/ioquake/ioq3 Quake 3], [https://www.mapeditor.org/ Tiled], [https://www.raylib.com/ 2d Raylib], [https://github.com/Rabios/awesome-raylib other raylib], [https://github.com/MrFrenik/gunslinger Gunslinger], [https://o3de.org/ o3d], [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/library GLFW], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/library Raylib 5], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games RPGMaker MV/MZ-compatible projects [https://github.com/Psychronic-Games/RPGReactor RPGReactor js],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Pinball [https://github.com/vpinball/vpinball vpinball], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games unpack unarc [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}


==Application Guides==

[[#top|...to the top]]

===Web Browser===

OWB is now at version 2.0 (which got an engine refresh, from July 2015 to February 2019) and 3.0.

This latest version has a good support for many/most web sites, even YouTube web page now works. [https://www.bilibili.tv/en/search untested] 

This improved compatibility comes at the expense of higher RAM usage (now 1GB RAM is the absolute minimum). 

Also, keep in mind that the lack of a JIT (Just-In-Time) JS compiler on the 32 bit version, makes the web surfing a bit slow. 

Only the 64 bit version of OWB 2.0 will have JIT enabled, thus benefitting of more speed. There are tooltypes that can be added to the icon to provide further features JIT, MSE etc 


Certificates from [https://curl.se/docs/caextract.html ca certs], 


DNS tracking blocking with [https://easylist.to/easylist/easylist.txt easylist.txt] in PROGDIR:Conf before starting browser with enabled AdBlock [https://github.com/easylist/easylist/tree/master easylist], [https://gitlab.com/eyeo anti abp], [https://firebog.net/ big blocklist], [https://github.com/StevenBlack/hosts Steves], [], [], 

This can be enabled with OWB Odyssey with Windows -&gt; Content Blocking and Windows -&gt; Messages and enter 

 https://www.youtube.com/api/stats/ads*
 https://www.youtube.com/pagead/adview*
 https://www.youtube.com#@##player-ads*

into your custom filters 


Element blocker browser extension might be needed for [https://github.com/easylist/easylist/wiki/Youtube-Issues youtube], [ mid roll], [ pre roll], [ ],  


OWB speed is much better when running from RAM Disk, the best way is to add the below into your S:User-Startup which copies OWB drawer from Extras:Internet/OWB to RAM Disk: 

So add this :
&lt;pre&gt;
copy Extras:Internet/OWB Ram:OWB/ ALL CLONE &gt;NIL:
copy Extras:Internet/OWB.info Ram: &gt;NIL:
&lt;/pre&gt;
Open RAM Disk and open OWB drawer and double click on OWB icon so that the above icon tooltypes are activated 

Problems are that the copy time is long (around 20 seconds added in the background), but we can make it faster if we delete useless files from the OWB drawer (docs, …)
If you don’t copy the drawer back onto the HD, you won’t save your cache, cookies, passwords… So you need a script for it.


Error messages 

SSL error &quot;cant verify with ca-certificates&quot;, check bios clock time date is correct 

Error 6, try checking networking prefs settings and Save / Use preferences again or a '''few times''' otherwise the network chipset may not be compatible with Aros 


[https://www.google.com/search?q=%s&amp;udm=14 Google search without AI overview] 


===E-mail===

 YAM does not support SSL and most mail providers now switched to encrypted SMTP/POP3 connections


====SimpleMail====

SimpleMail supports IMAP and appears to work with GMail, but it's never been reliable enough, it can crash with large mailboxes.

Please read more on this [http://www.freelists.org/list/simplemail-usr User list]


 GMail

Be sure to activate the pop3 usage in your gmail account setup / configuration first.

pop3: 
pop.gmail.com
Use SSL: Yes
Port: 995

smtp:
smtp.gmail.com (with authentication)
Use Authentication: Yes
Use SSL: Yes
Port: 465 or 587


 Hotmail/MSN/outlook/Microsoft Mail mid-2017, all outlook.com accounts will be migrated to Office 365 / Exchange

Most users are currently on POP which does not allow showing folders and many other features (technical limitations of POP3). With Microsoft IMAP you will get folders, sync read/unread, and show flags. You still won't get push though, as Microsoft has not turned on the IMAP Idle command as at Sept 2013.

If you want to try it, you need to first remove (you can't edit) your pop account (long-press the account on the accounts screen, delete account). Then set it up this way:

1. Email/Password
2. Manual
3. IMAP
4.

* Incoming: imap-mail.outlook.com, port 993, SSL/TLS should be checked
* Outgoing: smtp-mail.outlook.com, port 587, SSL/TLS should be checked
* POP server name pop-mail.outlook.com, port 995, POP encryption method SSL

 Yahoo  Mail

On April 24, 2002 Yahoo ceased to offer POP access to its free mail service. Introducing instead a yearly payment feature, allowing users POP3 and IMAP server support, along with such benefits as larger file attachment sizes and no adverts.

Sorry to see Yahoo leaving its users to cough up for the privilege of accessing their mail. Understandable, when competing against rivals such as Gmail and Hotmail who hold a large majority of users and were hacked in 2014 as well.


Incoming Mail (IMAP) Server

* Server - imap.mail.yahoo.com
* Port - 993
* Requires SSL - Yes

Outgoing Mail (SMTP) Server

* Server - smtp.mail.yahoo.com
* Port - 465 or 587
* Requires SSL - Yes
* Requires authentication - Yes

Your login info

* Email address - Your full email address (name@domain.com)
* Password - Your account's password
* Requires authentication - Yes


Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a subscription subs fee to have access to SMTP and POP3

* Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
* “Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
* “Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
* “Password” – Your Yahoo Mail password.

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

* Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.


====YAM Yet Another Mailer====

 YAM does not support SSL and most mail providers have now switched to encrypted SMTP/POP3 connections

This email client is POP3 only if the SSL library is available [http://www.freelists.org/list/yam YAM Freelists]

One of the downsides of using a POP3 mailer unfortunately - you have to set an option not to delete the mail if you want it left on the server. IMAP keeps all the emails on the server.

Possible issues

Sending mail issues is probably a matter of using your ISP's SMTP server, though it could also be an SSL issue.


getting a &quot;Couldn't initialise TLSv1 / SSL error

Use of on-line e-mail accounts with this email client is not possible as it lacks the OpenSSL AmiSSl v3 compatible library

 GMail 
Incoming Mail (POP3) Server - requires SSL: pop.gmail.com
Use SSL: Yes
Port: 995

Outgoing Mail (SMTP) Server - requires TLS: smtp.gmail.com (use authentication)
Use Authentication: Yes
Use STARTTLS: Yes (some clients call this SSL)
Port: 465 or 587

Account Name: your Gmail username (including '@gmail.com')
Email Address: your full Gmail email address (username@gmail.com)
Password: your Gmail password

Anyway, the SMTP is pop.gmail.com port 465 and it uses SSLLv3 Authentication. The POP3 settings are for the same server (pop.gmail.com), only on port 995 instead.


 Outlook.com access

&lt;pre &gt;
Outlook.com SMTP server address: smtp.live.com
Outlook.com SMTP user name: Your full Outlook.com email address (not an alias)
Outlook.com SMTP password: Your Outlook.com password
Outlook.com SMTP port: 587
Outlook.com SMTP TLS/SSL encryption required: yes 
&lt;/pre &gt;


 Yahoo  Mail

&lt;pre &gt;
“POP3 Server” – Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
“SMTP Server” – Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.
“Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
“Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
“Password” – Your Yahoo Mail password.
&lt;/pre &gt;

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a monthly fee to have access to SMTP and POP3


 Microsoft Outlook Express Mail 

1. Get the files to your PC.
By whatever method get the files off your Amiga onto your PC. In the YAM folder you have a number of different folders, one for each of your folders in YAM. Inside that is a file usually some numbers such as 332423.283. YAM created a new file for every single email you received.

2. Open up a brand new Outlook Express. Just configure the account to use 127.0.0.1 as mail servers. It doesn't really matter. You will need to manually create any subfolders you used in YAM.

3. You will need to do a mass rename on all your email files from YAM. Just add a .eml to the end of it. Amazing how PCs still rely mostly on the file name so it knows what sort of file it is rather than just looking at it! There are a number of multiple renamers online to download and free too.

4. Go into each of your folders, inbox, sent items etc. And do a select all then drag the files into Outlook Express (to the relevant folder obviously) Amazingly the file format that YAM used is very compatible with .eml standard and viola your emails appear. With correct dates and working attachments.

5. If you want your email into Microsoft Outlook. Open that up and create a new profile and a new blank PST file. Then go into File Import and choose to import from Outlook Express. And the mail will go into there. And viola.. you have your old email from your Amiga in a more modern day format.


===FTP===

Magellan has a great FTP module. It allows transferring files from/to a FTP server over the Internet or the local network and, even if FTP is perceived as a &quot;thing of the past&quot;, its usability is all inside the client. The FTP thing has a nice side effect too, since every Icaros machine can be a FTP server as well, and our files can be easily transferred from an Icaros machine to another with a little configuration effort.

First of all, we need to know the 'server' IP address. Server is the Icaros machine with the file we are about to download on another Icaros machine, that we're going to call 'client'. To do that, move on the server machine and 1) run Prefs/Services to be sure &quot;FTP file transfer&quot; is enabled (if not, enable it and restart Icaros); 2) run a shell and enter this command:

ifconfig -a

Make a note of the IP address for the network interface used by the local area network. For cabled devices, it usually is net0:. Now go on the client machine and run Magellan:

Perform these actions: 1) click on FTP; 2) click on ADDRESS BOOK; 3) click on &quot;New&quot;. 
You can now add a new entry for your Icaros server machine:

1) Choose a name for your server, in order to spot it immediately in the address book. Enter the IP address you got before.

2) click on Custom Options:


1) go to Miscellaneous in the left menu;

2) Ensure &quot;Passive Transfers&quot; is NOT selected;

3) click on Use. We need to deactivate Passive Transfers because YAFS, the FTP server included in Icaros, only allows active transfers at the current stage. Now, we can finally connect to our new file source:


1) Look into the address book for the newly introduced server, be sure that name and IP address are right, and

2) click on Connect. A new lister with server's &quot;MyWorkspace&quot; contents will appear. You can now transfer files over the network choosing a destination among your local (client's) volumes.

Can be adapted to any FTP client on any platform of your choice, just be sure your client allows Active Transfers as well.


===IRC Internet Relay Chat===

Jabberwocky is ideal for one-to-one social media communication, use IRC if you require one to many. 

Just type a message in ''lowercase''' letters and it will be posted to all in the [ AROS irc channel]. Please do not use UPPER CASE as it is a sign of SHOUTING which is annoying.

Other things to type in - replace &lt;message&gt; with a line of text and &lt;nick&gt; with a person's name

&lt;pre&gt;
/help

/list

/who
/whois &lt;nick&gt;

/msg &lt;nick&gt; &lt;message&gt;

/query &lt;nick&gt; 
&lt;message&gt;s
/query

/away &lt;message&gt;
/away

/quit &lt;going away message&gt; 
&lt;/pre&gt;


[http://irchelp.org/irchelp/new2irc.html#smiley Intro guide here]. IRC Primer can be found here in [http://www.irchelp.org/irchelp/ircprimer.html html], [http://www.irchelp.org/irchelp/text/ircprimer.txt TXT], [http://www.kei.com/irc/IRCprimer1.1.ps PostScript].


Issue the command /me &lt;text&gt; where &lt;text&gt; is the text that should follow your nickname.
Example: /me slaps ajk around a bit with a large trout

/nick &lt;newNick&gt;

/nickserv register &lt;password&gt; &lt;email address&gt;

/ns instead of /nickserv, while others might need /msg nickserv

/nickserv identify &lt;password&gt;

Alternatives:
/ns identify &lt;password&gt;
/msg nickserv identify &lt;password&gt;


==== IRC WookieChat ====

WookieChat is the most complete internet client for communication across the IRC Network. WookieChat allows you to swap ideas and communicate in real-time, you can also exchange Files, Documents, Images and everything else using the application's DCC capabilities.


add smilies drawer/directory

 run wookiechat from the shell and set stack to 1000000 e.g. wookiechat stack 1000000

select a server / server window

* nickname 
* user name 
* real name - optional

Once you configure the client with your preferred screen name, you'll want to find a channel to talk in.


servers

* New Server - click on this to add / add extra - change details in section below this click box 
* New Group
* Delete Entry
* Connect to server
* connect in new tab
* perform on connect

Change details

* Servername - change text in this box to one of the below Server: 
* Port number - no need to change
* Server password
* Channel - add #channel from below 
* auto join - can click this 
* nick registration password,

Click Connect to server button above


&lt;pre&gt;
Server: irc.freenode.net
Channel: #aros
&lt;/pre&gt;

irc://irc.freenode.net/aros

&lt;pre&gt;
Server: chat.amigaworld.net 
Channel: #amigaworld or #amigans 
&lt;/pre&gt;

&lt;pre&gt;
On Sunday evenings USA time usually starting around 3PM EDT (1900 UTC)
Server:irc.superhosts.net
Channel #team*amiga  
&lt;/pre&gt;

&lt;pre&gt;
BitlBee and Minbif are IRCd-like gateways to multiple IM networks
Server: im.bitlbee.org 
Port 6667 
Seems to be most useful on WookieChat as you can be connected to several servers at once. One for Bitlbee and any messages that might come through that. One for your normal IRC chat server. 
&lt;/pre&gt;

[http://www.bitlbee.org/main.php/servers.html Other servers],

&lt;pre&gt;
#Amiga.org - irc.synirc.net eu.synirc.net dissonance.nl.eu.synirc.net (IPv6: 2002:5511:1356:0:216:17ff:fe84:68a) 
twilight.de.eu.synirc.net zero.dk.eu.synirc.net us.synirc.net avarice.az.us.synirc.net envy.il.us.synirc.net harpy.mi.us.synirc.net 
liberty.nj.us.synirc.net snowball.mo.us.synirc.net - Ports 6660-6669 7001 (SSL)
&lt;/pre&gt;

&lt;pre&gt;
Multiple server support
&quot;Perform on connect&quot; scripts and channel auto-joins
Automatic Nickserv login
Tabs for channels and private conversations
CTCP PING, TIME, VERSION, SOUND
Incoming and Outgoing DCC SEND file transfers
Colours for different events
Logging and automatic reloading of logs
mIRC colour code filters
Configurable timestamps
GUI for changing channel modes easily
Configurable highlight keywords
URL Grabber window
Optional outgoing swear word filter
Event sounds for tabs opening, highlighted words, and private messages
DCC CHAT support
Doubleclickable URL's
Support for multiple languages using LOCALE
Clone detection
Auto reconnection to Servers upon disconnection
Command aliases
Chat display can be toggled between AmIRC and mIRC style
Counter for Unread messages
Graphical nicklist and graphical smileys with a popup chooser
&lt;/pre&gt;


====IRC Aircos ====

Double click on Aircos icon in Extras:Networking/Apps/Aircos. It has been set up with a guest account for trial purposes. Though ideally, choose a nickname and password for frequent use of irc. 


====IRC and XMPP Jabberwocky====
 Servers are setup and close down at random 
You sign up to a server that someone else has setup and access chat services through them. 

The two ways to access chat from jabberwocky
&lt;pre &gt;
Jabberwocky -&gt; Server -&gt; XMPP -&gt; open and ad-free 
Jabberwocky -&gt; Server -&gt; Transports (Gateways) -&gt; Proprietary closed systems 
&lt;/pre &gt;

The Jabber.org service connects with all IM services that use XMPP, the open standard for instant messaging and presence over the Internet. The services we connect with include Google Talk (closed), Live Journal Talk, Nimbuzz, Ovi, and thousands more. However, you can not connect from Jabber.org to proprietary services like AIM, ICQ, MSN, Skype, or Yahoo because they don’t yet use XMPP components (XEP-0114) '''but''' you can use Jabber.com's servers and IM gateways (MSN, ICQ, Yahoo etc.) instead.

The best way to use jabberwocky is in conjunction with a public jabber server with '''transports''' to your favorite services, like gtalk, Facebook, yahoo, ICQ, AIM, etc.


You have to register with one of the servers, [https://list.jabber.at/ this list] or [http://www.jabberes.org/servers/ another list], [http://xmpp.net/ this security XMPP list],

Unfortunately jabberwocky can only connect to one server at a time so it is best to check what services each server offers. If you set it up with separate Facebook and google talk accounts, for example, sometimes you'll only get one or the other.

Jabberwocky open a window where the Jabber server part is typed in as well as your Nickname and Password.

Jabber ID (JID) identifies you to the server and other users.

Once registered the next step is to goto Jabberwocky's &quot;Windows&quot; menu and select the &quot;Agents&quot; option. The &quot;Agents List&quot; window will open.

Roster (contacts list)

[http://search.wensley.org.uk/ Chatrooms] (MUC) are available

File Transfer - can send and receive files through the Jabber service but not with other services like IRC, ICQ, AIM or Yahoo. All you need is an installed webbrowser and OpenURL.

Clickable URLs - The message window uses Mailtext.mcc and you can set a URL action in the MUI mailtext prefs like SYS:Utils/OpenURL %s NEWWIN.

There is no consistent Skype like (H.323 VoIP) video conferencing available over Jabber. The move from xmpp to Jingle should help but no support on any amiga-like systems at the moment. [http://aminet.net/package/dev/src/AmiPhoneSrc192 AmiPhone] and [http://www.lysator.liu.se/%28frame,faq,nobg,useframes%29/ahi/v4-site/ Speak Freely] was an early attempt voice only contact. SIP and Asterisk are other PBX options.


 Facebook

If you're using the XMPP transport provided by Facebook themselves, chat.facebook.com, it looks like they're now requiring SSL transport. This means jabberwocky method below will no longer work. The best thing to do is to create an ID on a public jabber server which has a Facebook gateway.

&lt;pre &gt;
1. launch jabberwocky
2. if the login window doesn't appear on launch, select 'account' from the jabberwocky menu
3. your jabber ID will be user@chat.facebook.com where user is your user ID
4. your password is your normal facebook password
5. to save this for next time, click the popup gadget next to the ID field

6. click the 'add' button
7. click the 'close' button
8. click the 'connect' button
&lt;/pre &gt;

you're done. you can also click the 'save as default account' button if you want. jabberwocky configured to auto-connect when launching the program, but you can configure as you like. there is amigaguide documentation included with jabberwocky.

[http://amigaworld.net/modules/newbb/viewtopic.php?topic_id=37085&amp;forum=32 Read more here]

for Facebook users, you can log-in directly to Facebook with jabberwocky. just sign in as @chat.facebook.com with your Facebook password as the password


 Twitter

For a few years, there has been added a twitter transport. Servers include [http://jabber.hot-chilli.net/ jabber.hot-chili.net],  and .

An [http://jabber.hot-chilli.net/tag/how-tos/ How-to]

:Read [http://jabber.hot-chilli.net/2010/05/09/twitter-transport-working/ more]

 Instagram 

no support at the moment best to use a web browser based client

 ICQ

The new version (beta) of StriCQ uses a newer ICQ protocol. Most of the ICQ Jabber Transports still use an older ICQ protocol. You can only talk one-way to StriCQ using the older Transports. Only the newer ICQv7 Transport lets you talk both ways to StriCQ. Look at the server lists in the first section to check.

Register on a Jabber server, e.g. this one works: http://www.jabber.de/
Then login into Jabberwocky with the following login data e.g. xxx@jabber.de / Password: xxx Now add your ICQ account under the window-&gt;Agents-&gt;&quot;Register&quot;. Now Jabberwocky connects via the Jabber.de server with your ICQ account.

 Yahoo Messenger

although yahoo! does not use xmpp protocol, you should be able to use the transport methods to gain access and post your replies

 MSN

early months of 2013 Microsoft will ditch MSN Messenger client and force everyone to use Skype...but MSN protocol and servers will keep working as usual for quite a long time....

Occasionally the Messenger servers have been experiencing problems signing in.  You may need to sign in at www.outlook.com and then try again.  It may also take multiple tries to sign in.  (This also affects you if you’re using Skype.)

You have to check each servers' Agents List to see what transports (MSN protocol, ICQ protocol, etc.) are supported or use the list address' provided in the section above. Then register with each transport (IRC, MSN, ICQ, etc.) to which you need access. After registering you can Connect to start chatting.

msn.jabber.com/registered should appear in the window.

From this [http://tech.dir.groups.yahoo.com/group/amiga-jabberwocky/message/1378 JW group] guide which  helps with this process in a clear, step by step procedure.

1. Sign up on MSN's site for a passport account. This typically involves getting a Hotmail address.

2. Log on to the Jabber server of your choice and do the following:

* Select the &quot;Windows/Agents&quot; menu option in Jabberwocky.
* Select the MSN Agent from the list presented by the server.
* Click the Register button to open a new window asking for:
**Username = passort account email address, typically your hotmail address.
**Nick = Screen name to be shown to anyone you add to your buddy list.
**Password = Password for your passport account/hotmail address.
* Click the Register button at the bottom of the new window.

3. If all goes well, you will see the MSN Gateway added to your buddy list. If not, repeat part 2 on another server. Some servers may show MSN in their list of available agents, but have not updated their software for the latest protocols used by MSN.

4. Once you are registered, you can now add people to your buddy list. Note that you need to include the '''msn.''' ahead of the servername so that it knows what gateway agent to use. Some servers may use a slight variation and require '''msg.gate.''' before the server name, so try both to see what works.

If my friend's msn was amiga@hotmail.co.uk and my jabber server was @jabber.meta.net.nz..
then amiga'''%'''hotmail.com@'''msn.'''jabber.meta.net.nz

or another the trick to import MSN contacts is that you don't type the hotmail URL but the passport URL... e.g. Instead of: goodvibe%hotmail.com@msn.jabber.com  You type: goodvibe%passport.com@msn.jabber.com 
And the thing about importing contacts I'm afraid you'll have to do it by hand, one at the time...

 Google Talk

any XMPP server will work, but you have to add your contacts manually. a google talk user is typically either @gmail.com or @talk.google.com. a true gtalk transport is nice because it brings your contacts to you and (can) also support file transfers to/from google talk users.

implement Jingle a set of extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP)

support ended early 2014 as Google moved to Google+ Hangouts which uses it own proprietary format


===Video Player MPlayer===

Many of the menu features (such as doubling) do not work with the current version of mplayer but using

4:3
 mplayer -vf scale=800:600 file.avi

16:9
 mplayer -vf scale=854:480 file.avi

if you want gui use;
 mplayer -gui 1 &lt;other params&gt; file.avi

&lt;pre &gt;
stack 1000000

; using AspireOS 1.xx 
; copy FROM SYS:Extras/Multimedia/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 1.x 
; copy FROM SYS:Tools/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 2.x 
; copy FROM SYS:Utilities/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

cd RAM:MPlayer
run MPlayer -gui &gt; Nil:
;run MPlayer -gui -ao ahi_dev -playlist http://www.radio-paralax.de/listen.pls &gt; Nil: 
&lt;/pre &gt;

$ mplayer rtsp://127.0.0.1:554/sample_300kbit.mp4


MPlayer supports multicast streaming, and rtp/rtsp protocols (it might require [http://www.live555.com/openRTSP/ live555 library] to work with some streams). But you might have to build it where it's disabled. Also, multicast won't work with some AmiTCP-likes. MIAMI supported it, though.

AROS supports IPv4 (old but works) and this includes the needed address space for RTP.

If you mean multicast via RTP - mplayer handles it. You can even force UDP over TCP

-rtsp-stream-over-tcp

If the rtsp Real Time Streaming Protocol  server needs authentification:

-user -passwd


MPlayer - Menu - Open Playlist and load already downloaded .pls or .m3u file - auto starts around 4 percent cache

MPlayer - Menu - Open Stream and copy one of the .pls lines below into space allowed, press OK and press play button on main gui interface


Old 8bit 16bit remixes chip tune game music 
 
http://www.radio-paralax.de/listen.pls 

http://scenesat.com/

http://www.shoutcast.com/radio/Amiga

http://www.theoldcomputer.com/retro_radio/RetroRadio_Main.htm

http://www.kohina.com/

http://www.remix64.com/

http://retrogamer.net/forum/

http://retroasylum.podomatic.com/rss2.xml

http://retrogamesquad.com/

http://www.retronauts.com/

http://monsterfeet.com/noquarter/

http://www.retrogamingradio.com/

http://www.radiofeeds.co.uk/mp3.asp


[[#top|...to the top]]

====ZunePaint==== 

simplified typical workflow

* importing and organizing and photo management
* making global and regional local correction(s) - recalculation is necessary after each adjustment as it is not in real-time 
* exporting your images in the best format available with the preservation of metadata


Whilst achieving 80% of a great photo with just a filter, the remaining 20% comes from a manual fine-tuning of specific image attributes.


For photojournalism, documentary, and event coverage, minimal touching is recommended. Stick to Camera Raw for such shots, and limit changes to level adjustment, sharpness, noise reduction, and white balance correction.

For fashion or portrait shoots, a large amount of adjustment is allowed and usually ends up far from the original. Skin smoothing, blemish removal, eye touch-ups, etc. are common.  Might alter the background a bit to emphasize the subject.

Product photography usually requires a lot of sharpening, spot removal, and focus stacking.

For landscape shots, best results are achieved by doing the maximum amount of preparation before/while taking the shot. No amount of processing can match timing, proper lighting, correct gear, optimal settings, etc. Excessive post-processing might give you a dramatic shot but best avoided in the long term.


* White Balance - Left Amiga or F12 and K and under &quot;Misc color effects&quot; tab with a pull down for White Balance - color temperature also known as AKA tint (movies) or tones (painting) - warm temp raise red reduce green blue - cool raise blue lower red green 
* Exposure - exposure compensation, highlight/shadow recovery
* Noise Reduction - during RAW development or using external software
* Lens Corrections - distortion, vignetting, chromatic aberrations
* Detail - capture sharpening and local contrast enhancement
* Contrast - black point, levels (sliders) and curves tools (F12 and K) 
* Framing - straighten () and crop (F12 and F) 
* Refinements - color adjustments and selective enhancements - Left Amiga or F12 and K for RGB and YUV histogram tabs - 
* Resizing - enlarge for a print or downsize for the web or email (F12 and D) 
* Output Sharpening - customized for your subject matter and print/screen size


White Balance - F12 and K

scan your image for a shade which was meant to be white (neutral with each RGB value being equal) like paper or plastic which is in the same light as the subject of the picture. Use the dropper tool to select this color, similar colours will shift and you will have selected the perfect white balance for your part of the image - for the whole picture make sure RAZ or CLR button at the bottom is pressed before applying to the image above.


Exposure correction

F12 and K - YUV Y luminosity - RGB extra red tint - move red curve slightly down and move blue green curves slightly up

Workflows in practice

* Undo - Right AROS key or F12 and Z 
* Redo - Right AROS key or F12 and R

First flatten your image (if necessary) and then do a rotation until the picture looks level. 
* Crop the picture. Click the selection button and drag a box over the area of the picture you want to keep. Press the crop button and the rest of the photo will be gone. 
* Adjust your saturation, exposure, hue levels, etc., (right AROS Key and K for color correction) until you are happy with the photo. Make sure you zoom in all of the way to 100% and look the photo over, zoom back out and move around. Look for obvious problems with the picture. 
* After coloring and exposure do a sharpen (Right AROS key and E for Convolution and select drop down option needed), e.g. set the matrix to 5x5 (roughly equivalent Amount to 60%) and set the Radius to 1.0. Click OK.


And save your picture


Implemented or would like to see for simplification and ease of use

basic filters (presets) like black and white, monochrome, edge detection (sobel), motion/gaussian blur, 
* negative, sepiatone, retro vintage, night vision, colour tint, color gradient, color temperature, glows, fire, lightning, lens flare, emboss, filmic, pixelate mezzotint, antialias, etc.

adjust / cosmetic tools such as crop, 
* reshaping tools, straighten, smear, smooth, perspective, liquify, bloat, pucker, push pixels in any direction, dispersion, transform like warp, blending with soft light, page-curl, whirl, ripple, fisheye, neon,  etc. 
* red eye fixing, blemish remover, skin smoothing, teeth whitener, make eyes look brighter, desaturate,

effects like oil paint, cartoon, pencil sketch, charcoal, noise/matrix like sharpen/unsharpen, (right AROS key with A for Artistic effects) 
* blend two image, gradient blend, masking blend, explode, implode, custom collage, surreal painting, comic book style, needlepoint, stained glass, watercolor, mosaic, stencil/outline, crayon, chalk, etc.

borders such as 
* dropshadow, rounded, blurred, color tint, picture frame, film strip polaroid, bevelled edge, etc.

brushes e.g.
* frost, smoke, etc.

and manual control of

fix lens issues including vignetting (darkening), color fringing and barrel distortion, and chromatic and geometric aberration -  lens and body profiles

perspective correction

levels - directly modify the levels of the tone-values of an image, by using sliders for highlights, midtones and shadows

curves -  Color Adjustment and Brightness/Contrast

color balance

one single color transparent (alpha channel (color information/selections) for masking and/or blending ) for backgrounds, etc.

Threshold indicates how much other colors will be considered mixture of the removed color and non-removed colors

decompose layer into a set of layers with each holding a different type of pattern that is visible within the image

any selection using any selecting tools like lasso tool, marquee tool etc. the selection will temporarily be save to alpha 
If you create your image without transparency then the Alpha channel is not present, but you can add later.

File formats like .psd (Photoshop file has layers, masks etc.  contains edited sensor data. The original sensor data is no longer available) .xcf .raw .hdr

Image Picture Formats
* low dynamic range (JPEG, PNG, TIFF 8-bit), 16-bit (PPM, TIFF), typically as a 16-bit TIFF in either ProPhoto or AdobeRGB colorspace -  TIFF files are also fairly universal – although, if they contain proprietary data, such as Photoshop Adjustment Layers or Smart Filters, then they can only be opened by Photoshop making them proprietary.
* linear high dynamic range (HDR) images (PFM, [http://www.openexr.com/ ILM .EXR], jpg, [http://aminet.net/util/dtype cr2] (canon tiff based), hdr, NEF, CRW, ARW, MRW, ORF, RAF (Fuji), PEF, DCR, SRF, ERF, DNG files are RAW converted to an Adobe proprietary format - a container that can embed the raw file as well as the information needed to open it) 
An old version of [http://archives.aros-exec.org/index.php?function=browse&amp;cat=graphics/convert dcraw]

There is no single RAW file format. Each camera manufacturer has one or more unique RAW formats. RAW files contain the brightness levels data captured by the camera sensor. This data cannot be modified. A second smaller file, separate XML file, or within a database with instructions for the RAW processor to change exposure, saturation etc. The extra data can be changed but the original sensor data is still there. RAW is technically least compatible.

A raw file is high-bit (usually 12 or 14 bits of information) but a camera-generated TIFF file will be usually converted by the camera (compressed, downsampled) to 8 bits. The raw file has no embedded color balance or color space, but the TIFF has both. These three things (smaller bit depth, embedded color balance, and embedded color space) make it so that the TIFF will lose quality more quickly with image adjustments than the raw file. The camera-generated TIFF image is much more like a camera processed JPEG than a raw file. A strong advantage goes to the raw file. The power of RAW files, such as the ability to set any color temperature non-destructively and will contain more tonal values.

The principle of preserving the maximum amount of information to as late as possible in the process. The final conversion - which will always effectively represent a &quot;downsampling&quot; - should prevent as much loss as possible.

Once you save it as TIFF, you throw away some of that data irretrievably. When saving in the lossy JPEG format, you get tremendous file size savings, but you've irreversibly thrown away a lot of image data. As long as you have the RAW file, original or otherwise, you have access to all of the image data as captured.

Keyboard equivalence with Photoshop(tm) would help 

File
PHOTOSHOP	SHORTCUT	GIMP
New	Ctrl+n	New
Open	Ctrl+o	Open
Close	Ctrl+w	Close
Save	Ctrl+s	Save
Save as	Shift+Ctrl+s	Save as
Revert	F12	Revert
Print	Ctrl+p	Print
Exit	Ctrl+q	Quit
 
Edit
PHOTOSHOP	SHORTCUT	GIMP
Undo/Redo (1 level)	Ctrl+z	Undo (Redo is Shift+Ctrl+z)
Cut	Ctrl+x	Cut
Copy	Ctrl+c	Copy
Paste	Ctrl+v	Paste
Paste Into	Shift+Ctrl+v	Paste Into
Fill with FG color	Alt+Backspace	Fill with FG color
Fill with BG color	Control+Backspace	Fill with BG color
 
Image/Colors
PHOTOSHOP	SHORTCUT	GIMP
Levels	Ctrl+l	Levels
Auto Contrast	Shift+Ctrl+Alt+l	Stretch Contrast (same?)
Curves	Ctrl+m	Curves
Color Balance	Ctrl+b	Color Balance
Hue/Saturation	Ctrl+u	Hue-Saturation
Desaturate	Shift+Ctrl+u	Desaturate
Invert	Ctrl+i	Invert
Default Colors	d	Default Colors
Switch Colors	x	Switch Colors
 
Layer
PHOTOSHOP	SHORTCUT	GIMP
New Layer	Shift+Ctrl+n	New Layer
Layer via Copy	Ctrl+j	Duplicate Layer
Bring (layer) to Front	Shift+Ctrl+]	Layer to Top
Send (layer) to Back	Shift+Ctrl+[	Layer to Bottom
Bring (layer) Forward	Ctrl+]	Raise Layer
Send (layer) Backward	Ctrl+[	Lower Layer
Select Top Layer	Shift+Alt+]	Select Top Layer
Select Bottom Layer	Shift+Alt+[	Select Bottom Layer
Select One Layer Forward	Alt+]	Select Previous Layer
Select One Layer Backward	Alt+[	Select Next Layer
Merge Down	Ctrl+e	Merge Down
Merge Visible	Shift+Ctrl+e	Merge Visible
Preserve Transparency	/	Keep Transparency
Cycle Modes Forwards	Shift+=	Next Layer Mode
Cycle Modes Backwards	Shift+-	Previous Layer Mode
 
Select
PHOTOSHOP	SHORTCUT	GIMP
Select All	Ctrl+a	Select All
Deselect	Ctrl+d	Select None
Inverse	Shift+Ctrl+i	Invert
Feather	Ctrl+Alt+d	Feather
 
View
PHOTOSHOP	SHORTCUT	GIMP
Zoom In	Ctrl+=	Zoom In
Zoom Out	Ctrl+-	Zoom Out
Fit on Screen	Ctrl+0	Zoom to Fit Window
Actual Pixels	Ctrl+Alt+0	Zoom 1:1
Show/Hide Extras	Ctrl+h	Toggle Show Selection (close enough?)
Show/Hide Guides	Ctrl+'	Toggle Show Guides
Show/Hide Grid	Ctrl+Alt+'	Toggle Show Grid
Show/Hide Rulers	Ctrl+r	Toggle Show Rulers
Snap	Ctrl+;	Snap to Guides
Scroll View Up	Page Up	Scroll Page Up
Scroll View Down	Page Down	Scroll Page Down
Scroll View Left	Ctrl+Page Up	Scroll Page Left
Scroll View Right	Ctrl+Page Down	Scroll Page Right
 
Window/Dialogs
PHOTOSHOP	SHORTCUT	GIMP
?	F5	Tools Dialog
Color Tab	F6	Colors Dialog
Layers Tab	F7	Layers Dialog
Info Tab	F8	Image Information
 
Tools
PHOTOSHOP	SHORTCUT	GIMP
Rectangular Marquee Tool	m	Rect Select Tool
Elliptical Marquee Tool	Shift+m	Ellipse Select Tool
 	*This is a toggle between 'Elliptical Marquee Tool' and 'Rectangular Marquee Tool' in Photoshop	 
Move Tool	v	Move Tool
Lasso Tool	l	Free Select Tool
Magic Wand Tool	w	Fuzzy Select Tool
Crop Tool	c	Crop &amp; Resize Tool
Airbrush Tool	j	Airbrush Tool
Paintbrush Tool	b	Paintbrush Tool
Clone Stamp Tool	s	Clone Stamp Tool
Eraser Tool	e	Eraser Tool
Gradient Tool	g	Blend Tool
Paint Bucket Tool	Shift+g	Bucket Fill Tool
 	*This is a toggle between 'Paint Bucket Tool' and 'Gradient Tool' in Photoshop	 
Blur Tool	r	Convolve Tool
Dodge Tool	o	DodgeBurn Tool
Type Tool	t	Text Tool
Pen Tool	p	Bezier Select Tool
Eye Dropper Tool	i	Color Picker Tool
Zoom Tool	z	Magnify Tool
Previous Brush	,	Previous Brush
Next Brush	.	Next Brush
First Brush	Shift+&lt;	First Brush
Last Brush	Shift+&gt;	Last Brush
Decrease Brush Size	[	Decrease Brush Size
Increase Brush Size	]	Increase Brush Size
Decrease Brush Hardness	{	Decrease Brush Hardness
Increase Brush Hardness	}	Increase Brush Hardness
 
Help
PHOTOSHOP	SHORTCUT	GIMP
Help	F1	Help
Context Help	Shift+F1	Context Help
 
Misc.
PHOTOSHOP	SHORTCUT	GIMP
Last Filter	Ctrl+f	Repeat Last Filter
?	Shift+Ctrl+f	Reshow Last Filter
Preferences	Ctrl+k	Preferences
Liquify	Shift+Ctrl+x	IWarp (close enough?)
Toggle Quick Mask	q	Toggle Quick Mask


Spotlights - triangle of white opaque shape

Cutting out and/or replacing unwanted background or features - select large areas with the selection option like the Magic Wand tool (aka Color Range) or the Lasso (quick and fast) with feather 2 to soften edge or the pen tool which adds points/lines/Bézier curves (better control but slower), hold down the shift button as you click to add extra points/areas of the subject matter to remove. Increase the tolerance to cover more areas. To subtract from your selection hold down alt as you're clicking. 
* Layer masks are a better way of working than Erase they clip (black hides/hidden white visible/reveal). Clone Stamp can be simulated by   and brushes for other areas. 
* Leave the fine details like hair, fur, etc. to later with lasso and the shift key to draw a line all the way around your subject. Gradient Mapping - Inverse - Mask. i.e. Refine your selected image with edge detection and using the radius and edge options / adjuster (increase/decrease contrast) so that you will capture more fine detail from the background allowing easier removal. 
Remove fringe/halo

saving image as png rather than jpg/jpeg to keep transparency background intact.


Implemented [http://colorizer.org/ colour model representations] [http://paulbourke.net/texture_colour/colourspace/ Mathematical approach] - Photo stills are spatially 2d (h and w), but are colorimetrically 3d (r g and b, or H L S, or Y U V etc.) as well. 
* RGB - split cubed mapped color model for photos and computer graphics hardware using the light spectrum (adding and subtracting) 
* YUV - Y-Lightness U-blue/yellow V-red/cyan (similar to YPbPr and YCbCr) used in the PAL, NTSC, and SECAM composite digital TV color [http://crewofone.com/2012/chroma-subsampling-and-transcoding/#comment-7299 video]


Histograms

White balanced (neutral) if the spike happens in the same place in each channel of the RGB graphs. If not, you're not balanced. 
If you have sky you'll see the blue channel further off to the right.

RGB is best one to change colours. These elements RGB is a 3-channel format containing data for Red, Green, and Blue in your photo scale between 0 and 255. The area in a picture that appears to be brighter/whiter contains more red color as compared to the area which is relatively darker. Similarly in the green channel the area that appears to be darker contains less amount of green color as compared to the area that appears to be brighter.  Similarly in the blue channel the area appears to be darker contains less amount of blue color as compared to the area that appears to be brighter. Brightness luminance histogram also matches the green histogram more than any other color - human eye interprets green better e.g. RGB rough ratio 15/55/30%

RGBA (RGB+A, A means alpha channel) .  The alpha channel is used for &quot;alpha compositing&quot;, which can mostly be associated as &quot;opacity&quot;.  AROS deals in RGB with two digits for every color (red, green, blue), in ARGB you have two additional hex digits for the alpha channel.

The shadows are represented by the left third of the graph.  The highlights are represented by the right third.  And the midtones are, of course, in the middle.  The higher the black peaks in the graph, the more pixels are concentrated in that tonal range (total black area). 
By moving the black endpoint, which identifies the shadows (darkness) and a white light endpoint (brightness) up and down either sides of the graph, colors are adjusted based on these points. 
By dragging the central one, can increased the midtones and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .


RGB Curves

* Move left endpoint (black point) up or right endpoint (white point) up brightens 
* Move left endpoint down or right endpoint down darkens

Color Curves

* Dragging up on the Red Curve increases the intensity of the reds in the image but 
* Dragging down on the Red Curve decreases the intensity of the reds and thus increases the apparent intensity of its complimentary color, cyan. Green’s complimentary color is magenta, and blue’s is yellow.
&lt;pre&gt;
 Red &lt;-&gt; Cyan
 Green &lt;-&gt;Magenta
 Blue &lt;-&gt;Yellow 
&lt;/pre&gt;

YUV Best option to analyse and pull out statistical elements of any picture (i.e.  separate luminance data from color data). The line in Y luma tone box represents the brightness of the image with the point in the bottom left been black, and the point in the top right as white.  A low-contrast image has a concentrated clump of values nearer to the center of the graph. By comparison, a high-contrast image has a wider distribution of values across the entire width of the Histogram.   A histogram that is skewed to the right would indicate a picture that is a bit overexposed because most of the color data is on the lighter side (increase exposure with higher value F), while a histogram with the curve on the left shows a picture that is underexposed. This is good information to have when using post-processing software because it shows you not only where the color data exists for a given picture, but also where any data has been clipped (extremes on edges of either side): that is, it does not exist and, therefore, cannot be edited.  By dragging the endpoints of the line and as well as the central one, can increased the dark/shadows, midtones and light/bright parts and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .

The U and V chroma parts show color difference components of the image. It’s useful for checking whether or not the overall chroma is too high, and also whether it’s being limited too much
Can be used to create a negative image but also 
With U (Cb), the higher value you are, the more you're on the blue primary color. If you go to the low values then you're on blue complementary color, i.e. yellow.
With V (Cr), this is the same principle but with Red and Cyan.
e.g. If you push U full blue and V full red, you get magenta. If you push U full yellow and V full Cyan then you get green.

YUV simultaneously adds to one side of the color equation while subtracting from the other.  
using YUV to do color correction can be very problematic because each curve alters the result of each other: the mutual influence between U and V often makes things tricky. You may also be careful in what you do to avoid the raise of noise (which happens very easily). Best results are obtained with little adjustments

sunset that looks uninspiring and needs some color pop especially for the rays over the hill, a subtle contrast raise while setting luma values back to the legal range without hard clipping.


====Lunapaint====

Pixel based drawing app with onion-skin animation function

 Blocking, Shading, Coloring, adding detail 

&lt;pre&gt;
b BRUSH
e ERASER

alt eyedropper 
v layer tool 

z ZOOM / MAGNIFY &lt; &gt; n 
spc panning 
m  marque 
q lasso 
w same color selection / region 
&lt;/pre&gt;

&lt;pre&gt;
, LM RM
v 
V
f  filter 
F 
.  size 

p 
,  pick color 
[] last / next color 
&lt;/pre&gt;


There is not much missing in Lunapaint to be as good as FlipBook and then you have to take into account that Flipbook is considered to be amongst the best and easiest to use animation software out there. Ok to be honest Flipbook has some nice features that require more heavy work but those aren't so much needed right away, things like camera effects, sound, smart fill, export to different movie file formats etc.

Tried Flipbook with my tablet and compared it to Luna. The feeling is the same when sketching. LunaPaint is very responsive/fluent to draw with. Just as Flipbook is, and that responsiveness is something its users have mentioned as one of the positive sides of said software.

 author was learning MUI. Some parts just have to be rewritten with proper MUI classes before new features can be added.

* add [Frame Add] / [Frame Del]
* whole animation feature is impossible to use. If you draw 2 color maybe but if you start coloring your cells then you get in trouble
* pickup the entire image as a brush, not just a selection ? And consequently remove the brush from memory when one doesn't need it anymore. can pick up a brush and put it onto a new image but cropping isn't possible, nor to load/save brushes.
* Undo is something I longed for ages in Lunapaint.
* to import into the current layer, other types of images (e.g. JPEG) besides RAW64.
* implement graphic tablet features support


**GENERAL DRAWING**

Miss it very much:
UNDO
ERASER
COLORPICKER - has to show on palette too which color got picked.
BACKGROUND COLOR -Possibility to select from &quot;New project screen&quot;

Miss it somewhat:
ICON for UNDO
ICON for ERASER
ICON for CLEAR SCREEN ( What can I say? I start over from scratch very often )
BRUSH - possibility to cut out as brush not just copy off image to brush

**ANIMATING**

Miss it very much:
NUMBER OF CELLS - Possibity to change total no. of cells during project
ANIM BRUSH - Possibility to pick up a selected part of cells into an animbrush

Miss it somewhat:
ADD/REMOVE FRAMES: Add/remove single frame

In general LunaPaint is really well done and it feels like a new DeluxePaint version. It works with my tablet. Sure there's much missing of course but things can always be added over time. So there is great potential in LunaPaint that's for sure. Animations could be made in it and maybe put together in QuickVideo, saving in .gif or .mng etc some day.


LAYERS
-Layers names don't get saved globally in animation frames
-Layers order don't change globally in an animation (perhaps as default?).

EXPORTING IMAGES
-Exporting frames to JPG/PNG gives problems with colors. (wrong colors. See my animatiopn --&gt; My robot was blue now it's &quot;gold&quot; ) I think this only happens if you have layers.
-Trying to flatten the layers before export doesn't work if you have animation frames only the one you have visible will flatten properly all other frames are destroyed. (Only one of the layers are visible on them)
-Exporting images filenames should be for example e.g. file0001, file0002...file0010 instead as of now file1, file2...file10

LOAD/SAVE (Preferences)
-Make a setting for the default &quot;Work&quot; folder.

* Destroyed colors if exported image/frame has layers 
* mystic color cycling of the selected color while stepping frames back/forth (annoying)

&lt;pre&gt;
Deluxe Paint II enhanced key shortcuts 
    NOTE: @ denotes the ALT key

    [Technique]

    F1  - Paint
    F2  - Single Colour
    F3  - Replace
    F4  - Smear
    F5  - Shade
    F6  - Cycle
    F7  - Smooth
     M  - Colour Cycle

    [Brush]

     B  - Restore
     O  - Outline
     h  - Halve brush size
     H  - Double brush size
     x  - Flip brush on X axis
     X  - Double brush size on X axis only
     y  - Flip on Y 
     Y  - Double on Y
     z  - Rotate brush 90 degrees
     Z  - Stretch

    [Stencil]

     `  - Stencil On

    [Miscellaneous]

    F9  - Info Bar
    F10 - Selection Bar
    @o  - Co-Ordinates
    @a  - Anti-alias
    @r  - Colourise
    @t  - Translucent
    TAB - Colour Cycle

    [Picture]

     L  - Load
     S  - Save
     j  - Page to Spare(Flip)
     J  - Page to Spare(Copy)
     V  - View Page
     Q  - Quit

    [General Keys]

     m  - Magnify
     &lt;  - Zoom In
     &gt;  - Zoom Out
     [  - Palette Colour Up
     ]  - Palette Colour Down
     (  - Palette Colour Left
     )  - Palette Colour Right
     ,  - Eye Dropper
     .  - Pixel / Brush Toggle
     /  - Symmetry
     |  - Co-Ordinates
    INS - Perspective Control
    +/- - Brush Size (Fine Control)
     w  - Unfilled Polygon
     W  - Filled Polygon
     e  - Unfilled Ellipse
     E  - Filled Ellipse
     r  - Unfilled Rectangle
     R  - Filled Rectangle
     t  - Type/text tool
     a  - Select Font
    u/U - Undo
     d  - Brush
     D  - Filled Non-Uniform Polygon
    f/F - Fill Options
    g/G - Grid
    h/H - Brush Size (Coarse Control)
     K  - Clear
     c  - Unfilled Circle
     C  - Filled Circle
     v  - Line
     b  - Scissor Select and Toggle
     B  - Brush
    {,} - Toggle between two background colours
&lt;/pre&gt;

====Lodepaint====

Pixel based painting artwork app

====Grafx2====

Pixel based painting artwork app aesprite like 

[https://www.youtube.com/watch?v=59Y6OTzNrhk aesprite workflow keys and tablet use], [], 


====Vector Graphics ZuneFIG====

Vector Image Editing of files .svg .ps .eps


*Objects - raise lower rotate flip aligning snapping 
*Path - unify subtract intersect exclude divide 
*Colour - fill stroke 
*Stroke - size 
*Brushes - 
*Layers - 
*Effects - gaussian bevels glows shadows 
*Text    - 
*Transform - 


 AmiFIG ([http://epb.lbl.gov/xfig/frm_introduction.html xfig manual]) 

[[File:MyScreen.png|thumb|left|alt=Showing all Windows open in AmiFIG.|All windows available to AmiFIG.]]

for drawing simple to intermediate vector graphic images for scientific and technical uses and for illustration purposes for those with talent

;Menu options
* Load - fig format but import(s) SVG
* Save - fig format but export(s) eps, ps, pdf, svg and png
* PAN = Ctrl + Arrow keys 
* Deselect all points

There is no selected object until you apply the tool, and the selected object is not highlighted.

;Metrics - to set up page and styles - first window to open on new drawings

;Tools - Drawing Primitives - set Attributes window first before clicking any Tools button(s) 
* Shapes - circles, ellipses, arcs, splines, boxes,  polygon 
* Lines - polylines
* Text &quot;T&quot; button 
* Photos - bitmaps
* Compound - Glue, Break, Scale 
* POINTs - Move, Add, Remove 
* Objects - Move, Copy, Delete, Mirror, Rotate, Paste 
use right mouse button to stop extra lines, shapes being formed and the left mouse to select/deselect tools button(s)
* Rotate - moves in 90 degree turns centered on clicked POINT of a polygon or square

;Attributes which provide change(s) to the above primitives 
* Color
* Line Width
* Line Style
* arrowheads

;Modes 
Choose from freehand, charts, figures, magnet, etc.

;Library - allows .fig clip-art to be stored 
* compound tools to add .fig(s) together

;FIG 3.2 [http://epb.lbl.gov/xfig/fig-format.html Format] as produced by xfig version 3.2.5 
&lt;pre&gt;
Landscape
Center
Inches
Letter 
100.00
Single
-2
1200 2
4 0 0 50 -1 0 12 0.0000 4 135 1050 1050 2475 This is a test.01
&lt;/pre&gt;

# change the text alignment within the textbox. I can choose left, center, or right aligned by either changing the integer in the second column from 0 (left) to 1 or 2 (center, or right). 
# The third integer in the row specifies fontcolor. For instance, 0 is black, but blue is 1 and Green3 is 13.
# The sixth integer in the bottom row specifies fontface. 0 is Times-Roman, but 16 is Helvetica (a MATLAB default).
# The seventh number is fontsize. 12 represents a 12pt fontsize. Changing the fontsize of an item really is as easy as changing that number to 20.
# The next number is the counter-clockwise angle of the text. Notice that I have changed the angle to .7854 (pi/4 rounded to four digits=45 degrees).
# twelfth number is the position according to the standard “x-axis” in Xfig units from the left. Note that 1200 Xfig units is equivalent to once inch.
# thirteenth number is the “y-position” from the top using the same unit convention as before.

* The nested text string is what you entered into the textbox.
* The “01″ present at the end of that line in the .fig file is the closing tag. For instance, a change to \100 appends a @ symbol at the end of the period of that sentence.

; Just to note there are no layers, no 3d functions, no shading, no transparency, no animation


[[#top|...to the top]]

===Audio===


# AHI uses linear panning/balance, which means that in the center, you will get -6dB. If an app uses panning, this is what you will get. Note that apps like Audio Evolution need panning, so they will have this problem.

# When using AHI Hifi modes, mixing is done in 32-bit and sent as 32-bit data to the driver. The Envy24HT driver uses that to output at 24-bit (always).

# For the Envy24/Envy24HT, I've made 16-bit and 24-bit inputs (called Line-in 16-bit, Line-in 24-bit etc.). There is unfortunately no app that can handle 24-bit recording.


====Music Mods====

Digital module (mods) trackers are music creation software using samples and sometimes soundfonts, audio plugins (VST, AU or RTAS), MIDI.

Generally, MODs are similar to MIDI in that they contain note on/off and other sequence messages that control the mod player. Unlike (most) midi files, however, they also contain sound samples that the sequence information actually plays. MOD files can have many channels (classic amiga mods have 4, corresponding to the inbuilt sound channels), but unlike MIDI, each channel can typically play only one note at once. However, since that note might be a sample of a chord, a drumloop or other complex sound, this is not as limiting as it sounds.

Like MIDI, notes will play indefinitely if they're not instructed to end. Most trackers record this information automatically if you play your music in live. If you're using manual note entry, you can enter a note-off command with a keyboard shortcut - usually Caps Lock.

In fact when considering file size MOD is not always the best option. Even a dummy song wastes few kilobytes for nothing when a simple SID tune could be few hundreds bytes and not bigger than 64kB. AHX is another small format, AHX tunes are never larger than 64kB excluding comments.

[https://www.youtube.com/watch?v=rXXsZfwgil Protrekkr] (previously aka [w:Juan_Antonio_Arguelles_Rius|NoiseTrekkr])

If Protrekkr does not start, please check if the Unit 0 has been setup in the AHI prefs and still not, go to the directory utilities/protrekkr and double click on the Protrekkr icon

*Sample
*Note - Effect 
*Track (column) - Pattern - Order

It all starts with the Sample which is used to create Note(s) in a Track (column of a tracker) 
The Note can be changed with an Effect.  A Track of Note(s) can be collected into a Pattern (section of a song) and these can be given Order to create the whole song.

Patience (notes have to be entered one at a time) or playing the bassline on a midi controller (faster - see midi section above).  Best approach is to wait until a melody popped into your head.

*Up-tempo means the track should be reasonably fast, but not super-fast. 
*Groovy and funky imply the track should have some sort of &quot;swing&quot; feel, with plenty of syncopation or off beat emphasis and a recognizable, melodic bass line. 
*Sweet and happy mean upbeat melodies, a major key and avoiding harsh sounds.
*Moody - minor key

First, create a quick bass sound, which is basically a sine wave, but can be hand drawn for a little more variance. It could also work for the melody part, too.

This is usually a bass guitar or some kind of synthesizer bass. The bass line is often forgotten by inexperienced composers, but it plays an important role in a musical piece. Together with the rhythm section the bass line forms the groove of a song. It's the glue between the rhythm section and the melodic layer of a song.

The drums are just pink noise samples, played at different frequencies to get a slightly different sound for the kick, snare, and hihats.

Instruments that fall into the rhythm category are bass drums, snares, hi-hats, toms, cymbals, congas, tambourines, shakers, etc. Any percussive instrument can be used to form part of the rhythm section.

The lead is the instrument that plays the main melody, on top of the chords. There are many instruments that can play a lead section, like a guitar, a piano, a saxophone or a flute. The list is almost endless. There is a lot of overlap with instruments that play chords. Often in one piece an instrument serves both roles. The lead melody is often played at a higher pitch than the chords.

Listened back to what was produced so far, and a counter-melody can be imagined, which can be added with a triangle wave.

To give the ends of phrases some life, you can add a solo part with a crunchy synth. By hitting random notes in the key of G, then edited a few of them.

For the climax of the song, filled out the texture with a gentle high-pitch pad… …and a grungy bass synth.


The arrow at A points at the pattern order list. As you see, the patterns don't have to be in numerical order. This song starts with pattern &quot;00&quot;, then pattern &quot;02&quot;, then &quot;03&quot;, then &quot;01&quot;, etcetera. Patterns may be repeated throughout a song.

The B arrow points at the song title. Below it are the global BPM and speed parameters. These determine the tempo of the song, unless the tempo is altered through effect commands during the song.

The C arrow points at the list of instruments. An instrument may consist of multiple samples. Which sample will be played depends on the note. This can be set in the Instrument Editing screen. Most instruments will consist of just one sample, though. The sample list for the selected instrument can be found under arrow D.

Here's a part of the main editing screen. This is where you put in actual notes. Up to 32 channels can be used, meaning 32 sounds can play simultaneously. The first six channels of pattern &quot;03&quot; at order &quot;02&quot; are shown here. The arrow at A points at the row number. The B arrow points at the note to play, in this case a C4. The column pointed at by the C arrow tells us which instrument is associated with that note, in this case instrument #1 &quot;Kick&quot;.

The column at D is used (mainly) for volume commands. In this case it is left empty which means the instrument should play at its default volume. You can see the volume column being used in channel #6.

The E column tells us which effect to use and any parameters for that effect. In this case it holds the &quot;F&quot; effect, which is a tempo command. The &quot;04&quot; means it should play at tempo 4 (a smaller number means faster).

Base pattern

When I create a new track I start with what I call the base pattern. It is worthwhile to spend some time polishing it as a lot of the ideas in the base pattern will be copied and used in other patterns. At least, that's how I work. Every musician will have his own way of working. In &quot;Wild Bunnies&quot; the base pattern is pattern &quot;03&quot; at order &quot;02&quot;.

In the section about selecting samples I talked about the four different categories of instruments: drums, bass, chords and leads. That's also how I usually go about making the base pattern. I start by making a drum pattern, then add a bass line, place some chords and top it off with a lead. This forms the base pattern from which the rest of the song will grow.


Drums

Here's a screenshot of the first four rows of the base pattern. I usually reserve the first four channels or so for the drum instruments. Right away there are a couple of tricks shown here. In the first channel the kick, or bass drum, plays some notes. Note the alternating F04 and F02 commands. The &quot;F&quot; command alters the tempo of the song and by quickly alternating the tempo; the song will get some kind of &quot;swing&quot; feel.

In the second channel the closed hi-hat plays a fairly simple pattern. Further down in the channel, not shown here, some open hi-hat notes are added for a bit of variation.

In the third and fourth channel the snare sample plays. The &quot;8&quot; command is for panning. One note is panned hard to the left and the other hard to the right. One sample is played a semitone lower than the other. This results in a cool flanging effect. It makes the snare stand out a little more in the mix.


Bass line

There are two different instruments used for the bass line. Instrument #6 is a pretty standard synthesized bass sound. Instrument #A sounds a bit like a slap bass when used with a quick fade out. By using two different instruments the bass line sounds a bit more ”human”. The volume command is used to cut off the notes. However, it is never set to zero. Setting the volume to a very small value will result in a reverb-like effect. This makes the song sound more &quot;live&quot;.

The bass line hints at the chords that will be played and the key the song will be in. In this case the key of the song is D-major, a positive and happy key.


Chords

The D major chords that are being played here are chords stabs; short sounds with a quick decay (fade out). Two different instruments (#8 and #9) are used to form the chords. These instruments are quite similar, but have a slightly different sound, panning and volume decay. Again, the reason for this is to make the sound more human. The volume command is used on some chords to simulate a delay, to achieve more of a live feel. The chords are placed off-beat making for a funky rhythm.


Lead

Finally the lead melody is added. The other instruments are invaluable in holding the track together, but the lead melody is usually what catches people's attention.

A lot of notes and commands are used here, but it looks more complex than it is. A stepwise ascending melody plays in channel 13. Channel 14 and 15 copy this melody, but play it a few rows later at a lower volume. This creates an echo effect. A bit of panning is used on the notes to create some stereo depth. Like with the bass line, instead of cutting off notes the volume is set to low values for a reverb effect. The &quot;461&quot; effect adds a little vibrato to the note, which sounds nice on sustained notes.

Those paying close attention may notice the instrument used here for the lead melody is the same as the one used for the bass line (#6 &quot;Square&quot;), except played two or three octaves higher. This instrument is a looped square wave sample. Each type of wave has its own quirks, but the square wave (shown below) is a really versatile wave form.

Song structure

Good, catchy songs are often carefully structured into sections, some of which are repeated throughout the song with small variations.

A typical pop-song structure is: Intro - Verse - Chorus - Verse - Chorus - Bridge - Chorus.

Other single sectional song structures are

&lt;pre&gt;
Strophic or AAA Song Form - oldest story telling with refrain (often title of the song) repeated in every verse section melody 
AABA Song Form - early popular, jazz and gospel fading during the 1960s 
AB or Verse/Chorus Song Form - songwriting format of choice for modern popular music since the 1960s 
Verse/Chorus/Bridge Song Form
ABAB Song Form
ABAC Song Form
ABCD Song Form
AAB 12-Bar Song Form - three four-bar lines or sub-sections 
8-Bar Song Form
16-Bar Song Form
Hybrid / Compound Song Forms
&lt;/pre&gt;

The most common building blocks are:

#INTRODUCTION(INTRO)
#VERSE
#REFRAIN
#PRE-CHORUS / RISE / CLIMB
#CHORUS
#BRIDGE
#MIDDLE EIGHT
#SOLO / INSTRUMENTAL BREAK
#COLLISION
#CODA / OUTRO
#AD LIB (OFTEN IN CODA / OUTRO)

The chorus usually has more energy than the verse and often has a memorable melody line. As the chorus is repeated the most often during the song, it will be the part that people will remember.

The bridge often marks a change of direction in the song. It is not uncommon to change keys in the bridge, or at least to use a different chord sequence. The bridge is used to build up tension towards the big finale, the last repetition of chorus.


 Playing

RCTRL:                           Play song from row 0.

LSHIFT + RCTRL:                  Play song from current row.

RALT:                            Play pattern from row 0.

LSHIFT + RALT:                   Play pattern from current row.

Left mouse on '&gt;':               Play song from row 0.

Right mouse on '&gt;':              Play song from current row.

Left mouse on '|&gt;':              Play pattern from row 0.

Right mouse on '|&gt;':             Play pattern from current row.

Left mouse on 'Edit/Record':     Edit mode on/off.

Right mouse on 'Edit/Record':    Record mode on/off.


 Editing 


LSHIFT + ESCAPE:                 Switch large patterns view on/off

TAB:                    Go to next track

LSHIFT + TAB:                    Go to prev. track

LCTRL + TAB:                    Go to next note in track

LCTRL + LSHIFT + TAB:           Go to prev. note in track

SPACE:                           Toggle Edit mode On &amp; Off

(Also stop if the song is being played)

SHIFT SPACE:                     Toggle Record mode On &amp; Off

(Wait for a key note to be pressed

or a midi in message to be received)

DOWN ARROW:                      1 Line down

UP ARROW:                        1 Line up

LEFT ARROW:                      1 Row left

RIGHT ARROW:                     1 Row right

PREV. PAGE:                      16 Arrows Up

NEXT PAGE:                       16 Arrows Down

HOME / END:                      Top left / Bottom right of pattern

LCTRL + HOME / END:              First / last track

F5, F6, F7, F8, F9:              Jump to 0, 1/4, 2/4, 3/4, 4/4 lines of the patterns

+ - (Numeric keypad):           Next / Previous pattern

LCTRL + LEFT / RIGHT:           Next / Previous pattern

LCTRL + LALT + LEFT / RIGHT:    Next / Previous position

LALT + LEFT / RIGHT:           Next / Previous instrument

LSHIFT + M:                      Toggle mute state of the current channel

LCTRL + LSHIFT + M:             Solo the current track / Unmute all

LSHIFT + F1 to F11:              Select a tab/panel

LCTRL + 1 to 4:                 Select a copy buffer


 Tracking 

1st and 2nd keys rows:           Upper octave row

3rd and 4th keys rows:           Lower octave row

RSHIFT:                          Insert a note off

/ and * (Numeric keypad)

or F1 F2:                        -1 or +1 octave

INSERT / BACKSPACE:              Insert or Delete a line in current track

or current selected block.

LSHIFT + INSERT / BACKSPACE:     Insert or Delete a line in current pattern

DELETE (NOT BACKSPACE):          Empty a column or a selected block.


 Blocks

(Blocks can also be selected with the mouse by holding the right button and scrolling the pattern with the mouse wheel).


LCTRL + A:          Select entire current track

LCTRL + LSHIFT + A: Select entire current pattern

LALT + A:          Select entire column note in a track

LALT + LSHIFT + A: Select all notes of a track

LCTRL + X:          Cut the selected block and copy it into the block-buffer

LCTRL + C:          Copy the selected block into the block-buffer

LCTRL + V:          Paste the data from the block buffer into the pattern

LCTRL + I:          Interpolate selected data from the first to the last row of a selection

LSHIFT + ARROWS

PREV. PAGE

NEXT PAGE: Select a block

LCTRL + R:          Randomize the select columns of a selection, works similar to CTRL + I (interpolating them)

LCTRL + U:          Transpose the note of a selection to 1 seminote higher

LCTRL + D:          Transpose the note of a selection to 1 seminote lower

LCTRL + LSHIFT + U: Transpose the note of a selection to 1 seminote higher (only for the current instrument)

LCTRL + LSHIFT + D: Transpose the note of a selection to 1 seminote lower  (only for the current instrument)

LCTRL + H:          Transpose the note of a selection to 1 octave higher

LCTRL + L:          Transpose the note of a selection to 1 octave lower

LCTRL + LSHIFT + H: Transpose the note of a selection to 1 octave higher (only for the current instrument)

LCTRL + LSHIFT + L: Transpose the note of a selection to 1 octave lower (only for the current instrument)

LCTRL + W:          Save the current selection into a file


 Misc 


LALT + ENTER:     Switch between full screen / windowed mode

LALT + F4:        Exit program (Windows only)

LCTRL + S:         Save current module

LSHIFT + S:         Switch top right panel to synths list

LSHIFT + I:         Switch top right panel to instruments list


&lt;pre&gt;
C-x   xh xx xx hhhh             Volume 
B-x   xh xx xx hhhh             Jump to 
A#x  xh xx xx hhhh hhhh   Slide 
F-x    xh xx xx hhhh            Tempo 
D-x   xh xx xx hhhh             Pattern Break 
G#x  xh xx xx hhhh
&lt;/pre&gt;

h Hex 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13

d Dec 01 02 03 04 05 06 07 08 09 10  11 12 13 14 15 16 17 18 19

The Set Volume command: C. Input a note, then move the cursor to the effects command column and type a C. Play the pattern, and you shouldn't be able to hear the note you placed the C by. This is because the effect parameters are 00. Change the two zeros to a 40(Hex)/64(Dec), depending on what your tracker uses. Play back the pattern again, and the note should come in at full volume.

The Position Jump command next. This is just a B followed by the position in the playing list that you want to jump to. One thing to remember is that the playing list always starts at 0, not 1. This command is usually in Hex.

Onto the volume slide command: A. This is slightly more complex (much more if you're using a newer tracker, if you want to achieve the results here, then set slides to Amiga, not linear), due to the fact it depends on the secondary tempo. For now set a secondary tempo of 06 (you can play around later), load a long or looped sample and input a note or two. A few rows after a note type in the effect command A. For the parameters use 0F. Play back the pattern, and you should notice that when the effect kicks in, the sample drops to a very low volume very quickly. Change the effect parameters to F0, and use a low volume command on the note. Play back the pattern, and when the slide kicks in the volume of the note should increase very quickly.
This because each part of the effect parameters for command A does a different thing. The first number slides the volume up, and the second slides it down. It's not recommended that you use both a volume up and volume down at the same time, due to the fact the tracker only looks for the first number that isn't set to 0. If you specify parameters of 8F, the tracker will see the 8, ignore the F, and slide the volume up. Using a slide up and down at same time just makes you look stupid. Don't do it...

The Set Tempo command: F, is pretty easy to understand. You simply specify the BPM (in Hex) that you want to change to. One important thing to note is that values of lower than 20 (Hex) sets the secondary tempo rather than the primary.

Another useful command is the Pattern Break: D. This will stop the playing of the current pattern and skip to the next one in the playing list. By using parameters of more than 00 you can also specify which line to begin playing from.

Command 3 is Portamento to Note. This slides the currently playing note to another note, at a specified speed. The slide then stops when it reaches the desired note. 
&lt;pre&gt;
   C-2 1 000 - Starts the note playing
   ---      000
   C-3    330 - Starts the slide to C-3 at a speed of 30.
   ---     300 - Continues the slide
   ---     300 - Continues the slide
&lt;/pre&gt;
Once the parameters have been set, the command can be input again without any parameters, and it'll still perform the same function unless you change the parameters. This memory function allows certain commands to function correctly, such as command 5, which is the Portamento to Note and Volume Slide command. Once command 3 has been set up command 5 will simply take the parameters from that and perform a Portamento to Note. Any parameters set up for command 5 itself simply perform a Volume Slide identical to command A at the same time as the Portamento to Note.

This memory function will only operate in the same channel where the original parameters were set up.
There are various other commands which perform two functions at once. They will be described as we come across them.

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  00

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  02

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  05

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  08

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0A

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0D

C-3  04  ..  ..  09  10 ---&gt; C-3  04  ..  ..  09  10

(You can also switch on the Slider Rec to On, and perform parameter-live-recording, such as cutoff transitions, resonance or panning tweaking, etc..)  Note: this command only works for volume/panning and fx datas columns.


The next command we'll look at is the Portamento up/down: 1 and 2. Command 1 slides the pitch up at a specified speed, and 2 slides it down. This command works in a similar way to the volume slide, in that it is dependent on the secondary tempo. Both these commands have a memory dependent on each other, if you set the slide to a speed of 3 with the 1 command, a 2 command with no parameters will use the speed of 3 from the 1 command, and vice versa.

Command 4 is Vibrato. Vibrato is basically rapid changes in pitch, just try it, and you'll see what I mean. Parameters are in the format of xy, where x is the speed of the slide, and y is the depth of the slide. One important point to remember is to keep your vibratos subtle and natural so a depth of 3 or less and a reasonably fast speed, around 8, is usually used. Setting the depth too high can make the part sound out of tune from the rest.
Following on from command 4 is command 6. This is the Vibrato and Volume Slide command, and it has a memory like command 5, which you already know how to use.

Command 7 is Tremolo. This is similar to vibrato. Rather than changing the pitch it slides the volume. The effect parameters are in exactly the same format.   vibrato effect (0x1dxy) x = speed y = depth (can't be used if arpeggio (0x1b) is turned on) 

&lt;pre&gt;
 C-7 00 .. .. 1B37 &lt;-  Turn Arpeggio effect on
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B38 &lt;- Change datas
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B00 &lt;- Turn it off
&lt;/pre&gt;

Command 9 is Sample Offset. This starts the playback of the sample from a different place than the start. The effect parameters specify the sample offset, but only very roughly. Say you have a sample which is 8765(Hex) bytes long, and you wanted it to play from position 4321(Hex). The effect parameter could only be as accurate as the 43 part, and it would ignore the 21.

Command B is the Playing List/Order Jump command. The parameters specify the position in the Playing List/Order to jump to. When used in conjunction with command D you can specify the position and the line to play from.

Command E is pretty complex, as it is used for a lot of different things, depending on what the first parameter is. Let's take a trip through each effect in order.
Command E0 controls the hardware filter on an Amiga, which, as a low pass filter, cuts off the highest frequencies being played back. There are very few players and trackers on other system that simulate this function, not that you should need to use it. The second parameter, if set to 1, turns on the filter. If set to 0, the filter gets turned off.

Commands E1/E2 are Fine Portamento Up/Down. Exactly the same functions as commands 1/2, except that they only slide the pitch by a very small amount. These commands have a memory the same as 1/2 as well.

Command E3 sets the Glissando control. If parameters are set to 1 then when using command 3, any sliding will only use the notes in between the original note and the note being slid to. This produces a somewhat jumpier slide than usual. The best way to understand is to try it out for yourself. Produce a slow slide with command 3, listen to it, and then try using E31.

Command E4 is the Set Vibrato Waveform control. This command controls how the vibrato command slides the pitch. Parameters are 0 - Sine, 1 - Ramp Down (Saw), 2 - Square. By adding 4 to the parameters, the waveform will not be restarted when a new note is played e.g. 5 - Sine without restart.

Command E5 sets the Fine Tune of the instrument being played, but only for the particular note being played. It will override the default Fine Tune for the instrument. The parameters range from 0 to F, with 0 being -8 and F being +8 Fine Tune. A parameter of 8 gives no Fine Tune. If you're using a newer tracker that supports more than -8 to +8 e.g. -128 to +128, these parameters will give a rough Fine Tune, accurate to the nearest 16.

Command E6 is the Jump Loop command. You mark the beginning of the part of a pattern that you want to loop with E60, and then specify with E6x the end of the loop, where x is the number of times you want it to loop.

Command E7 is the Set Tremolo Waveform control. This has exactly the same parameters as command E4, except that it works for Tremolo rather than Vibrato.

Command E9 is for Retriggering the note quickly. The parameter specifies the interval between the retrigs. Use a value of less than the current secondary tempo, or else the note will not get retrigged.

Command EA/B are for Fine Volume Slide Up/Down. Much the same as the normal Volume Slides, except that these are easier to control since they don't depend on the secondary tempo. The parameters specify the amount to slide by e.g. if you have a sample playing at a volume of 08 (Hex) then the effect EA1 will slide this volume to 09 (Hex). A subsequent effect of EB4 would slide this volume down to 05 (Hex).

Command EC is the Note Cut. This sets the volume of the currently playing note to 0 at a specified tick. The parameters should be lower than the secondary tempo or else the effect won't work.

Command ED is the Note Delay. This should be used at the same time as a note is to be played, and the parameters will specify the number of ticks to delay playing the note. Again, keep the parameters lower than the secondary tempo, or the note won't get played!

Command EE is the Pattern Delay. This delays the pattern for the amount of time it would take to play a certain number of rows. The parameters specify how many rows to delay for.

Command EF is the Funk Repeat command. Set the sample loop to 0-1000. When EFx is used, the loop will be moved to 1000- 2000, then to 2000-3000 etc. After 9000-10000 the loop is set back to 0- 1000. The speed of the loop &quot;movement&quot; is defined by x. E is two times as slow as F, D is three times as slow as F etc. EF0 will turn the Funk Repeat off and reset the loop (to 0-1000).

effects 0x41 and 0x42 to control the volumes of the 2 303 units

There is a dedicated panel for synth parameter editing with coherent sections (osc, filter modulation, routing, so on) the interface is much nicer, much better to navigate with customizable colors, the reverb is now customizable (10 delay lines), It accepts newer types of Waves (higher bit rates, at least 24). Has a replay routine.

It's pretty much your basic VA synth. The problem isn't with the sampler being to high it's the synth is tuned two octaves too low, but if you want your samples tuned down just set the base note down 2 octaves (in the instrument panel).

so the synth is basically divided into 3 sections from left to right: oscillators/envelopes, then filter and LFO's, and in the right column you have mod routings and global settings.

for the oscillator section you have two normal oscillators (sine, saw, square, noise), the second of which is tunable, the first one tunes with the key pressed. Attached to OSC 1 is a sub-oscillator, which is a sawtooth wave tuned one octave down. The phase modulation controls the point in the duty cycle at which the oscillator starts. The ADSR envelope sliders (grouped with oscs) are for modulation envelope 1 and 2 respectively. you can use the synth as a sampler by choosing the instrument at the top.

In the filter column, the filter settings are: 1 = lowpass, 2 = highpass, 3 = off. cutoff and resonance. For the LFOs they are LFO 1 and LFO 2, the ADSR sliders in those are for the LFO itself.

For the modulation routings you have ENV 1, LFO 1 for the first slider and ENV 2, LFO 2 for the second, you can cycle through the individual routings there, and you can route each modulation source to multiple destinations of course, which is another big plus for this synth. Finally the glide time is for portamento and master volume, well, the master volume... it can go quite loud.

The sequencer is changed too, It's more like the one in AXS if you've used that, where you can mute tracks to re-use patterns with variation.


&lt;pre&gt;
Support for the following modules formats:
669 (Composer 669, Unis 669), 
AMF (DSMI Advanced Module Format), 
AMF (ASYLUM Music Format V1.0), 
APUN (APlayer), DSM (DSIK internal format), 
FAR (Farandole Composer), 
GDM (General DigiMusic), 
IT (Impulse Tracker), 
IMF (Imago Orpheus), 
MOD (15 and 31 instruments), 
MED (OctaMED), 
MTM (MultiTracker Module editor), 
OKT (Amiga Oktalyzer), 
S3M (Scream Tracker 3), 
STM (Scream Tracker), 
STX (Scream Tracker Music Interface Kit), 
ULT (UltraTracker), 
UNI (MikMod), 
XM (FastTracker 2),
Mid (midi format via timidity)
&lt;/pre&gt;


Possible plugin options include [http://lv2plug.in/ LV2],


====Midi - Musical Instrument Digital Interface====

A midi file typically contains music that plays on up to 16 channels (as per the midi standard), but many notes can simultaneously play on each channel (depending on the limit of the midi hardware playing it).

'''Timidity'''

Although usually already installed, you can uncompress the [http://www.libsdl.org/projects/SDL_mixer/ timidity.tar.gz (14MB)] into a suitable drawer like below's SYS:Extras/Audio/ 
 assign timidity: SYS:Extras/Audio/timidity
added to SYSːs/User-Startup

'''WildMidi playback'''


'''Audio Evolution 4 (2003) 4.0.23 (from 2012)'''


*Sync Menu    - CAMD Receive, Send checked 
*Options Menu - MIDI Machine Control - Midi Bar Display - Select CAMD MIDI in / out - Midi Remote Setup 


MCB Master Control Bus 
*Sending a MIDI start-command and a Song Position Pointer, you can synchronize audio with an external MIDI sequencer (like B&amp;P). 
*B&amp;P Receive, start AE, add AudioEvolution.ptool in Bars&amp;Pipes track, press play / record in AE then press play in Pipes 
*CAMD Receive, receive MIDI start or continue commands via camd.library sync to AE 


*MIDI Machine Control
*Midi Bar Display 
*Select CAMD MIDI in / out
*Midi Remote Setup - open requester for external MIDI controllers to control app mixer and transport controls cc remotely 
 Channel   - mixer(vol, pan, mute, solo), eq, aux, fx, 
 Subgroup  - Volume, Mute, Solo 
 Transport - Start, End, Play, Stop, Record, Rewind, Forward 
 Misc      - Master vol., Bank Down, Bank up 


&lt;pre&gt;
q        - quit 

First 3 already opened when AE started 
F1       - timeline window
F2       - mixer 
F3       - control 
F4       - subgroups 
F5       - aux returns 
F6       - sample list 

i        - Load sample to use 

space    - start/stop play 
b        - reset time 0:00


s        - split mode 
r        - open recording window 
a        - automation edit mode with p panning, m mute and v volume 


[ / ]    - zoom in / out 
:        - previous track
*        - next track 

x c v f  - cut copy paste cross-fade 
g        - snap grid 


&lt;/pre&gt;


 '''[http://bnp.hansfaust.de/ Bars n Pipes sequencer]'''

 BarsnPipes debug ... in shell 

Menu (right mouse)  
*Song        - Songs load and save in .song format but option here to load/save Midi_Files .mid in FORMAT0 or FORMAT1 
*Track       - 
*Edit        -
*Tool        - 
*Timing      - SMTPE Synchronizing 
*Windows     - 
*Preferences - Multiple MIDI-in option 

Windows (some of these are usually already opened when Bars n Pipes starts up for the first time) 
*Workflow -&gt; Tracks, .... Song Construction, Time-line Scoring, Media Madness, Mix Maestro, 
*Control  -&gt; Transport (or mini one), Windows (which collects all the Windows icons together-shortcut), .... Toolbox, Accessories, Metronome, 

Once you have your windows placed on the screen that suits your workflow, Song -&gt; Save as Default will save the positions, colors, icons, etc as you'd like them 

If you need a particular setup of Tracks, Tools, Tempos etc, you save them all as a new song you can load each time 

Right mouse menu -&gt; Preferences -&gt; Environment... -&gt; ScreenMode  - Linkages for Synch (to Slave) usbmidi.out.0 and Send (Master) usbmidi.in.0 - Clock MTC 


'''Tracks'''

#Double-click on B&amp;P's icon. B&amp;P will then open with an empty Song. You can also double-click on a song icon to open a song in B&amp;P.
#Choose a track. The B&amp;P screen will contain a Tracks Window with a number of tracks shown as pipelines (Track 1, Track 2, etc...). To choose a track, simply click on the gray box to show an arrow-icon to highlight it. This icon show whether a track is chosen or not. To the right of the arrow-icon, you can see the icon for the midi-input. If you double-click on this icon you can change the MIDI-in setup.
#Choose Record for the track. To the right of the MIDI-input channel icon you can see a pipe. This leads to another clickable icon with that shows either P, R or M. This stands for Play, Record or Merge. To change the icon, simply click on it. If you choose P, this track can only play the track (you can't record anything). If you choose R, you can record what you play and it overwrites old stuff in the track. If you choose M, you merge new records with old stuff in the track. Choose R now to be able to make a record.
#Chose MIDI-channel. On the most right part of the track you can see an icon with a number in it. This is the MIDI-channel selector. Here you must choose a MIDI-channel that is available on your synthesizer/keyboard. If you choose General MIDI channel 10, most synthesizer will play drum sounds. To the left of this icon is the MIDI-output icon. Double-click on this icon to change the MIDI-output configuration.
#Start recording. The next step is to start recording. You must then find the control buttons (they look like buttons on a CD-player). To be able to make a record. you must click on the R icon. You can simply now press the play button (after you have pressed the R button) and play something on you keyboard. To playback your composition, press the Play button on the control panel.
#Edit track. To edit a track, you simply double click in the middle part of a track. You will then get a new window containing the track, where you can change what you have recorded using tools provided. Take also a look in the drop-down menus for more features.


Videos to help understand [https://www.youtube.com/watch?v=A6gVTX-9900 small intro], [https://www.youtube.com/watch?v=abq_rUTiSA4&amp;t=3s Overview], [https://www.youtube.com/watch?v=ixOVutKsYQo Workplace Setup CC PC Sysex], [https://www.youtube.com/watch?v=dDnJLYPaZTs Import Song], [https://www.youtube.com/watch?v=BC3kkzPLkv4 Tempo Mapping], [https://www.youtube.com/watch?v=sd23kqMYPDs ptool Arpeggi-8], [https://www.youtube.com/watch?v=LDJq-YxgwQg  PlayMidi Song], [https://www.youtube.com/watch?v=DY9Pu5P9TaU Amiga Midi], [https://www.youtube.com/watch?v=abq_rUTiSA4 Learning Amiga bars and Pipes], 

Groups like [https://groups.io/g/barsnpipes/topics this] could help 


'''Tracks window'''

* blue &quot;1 2 3 4 5 6 7 8 Group&quot; and transport tape deck VCR-type controls
* Flags 
* [http://theproblem.alco-rhythm.com/org/bp.html Track 1, Track2, to Track 16, on each Track there are many options that can be activated] 

Each Track has a 

*Left LHS  - Click in grey box to select what Track to work on, Midi-In ptool icon should be here (5pin plug icon), and many more from the Toolbox on the Input Pipeline 
*Middle    - (P, R, M) Play, Record, Merge/Multi before the sequencer line and a blue/red/yellow (Thru Mute Play) Tap 
*Right RHS - Output pipeline, can have icons placed uopn it with the final ptool icon(s) being the 5pin icon symbol for Midi-OUT 

Clogged pipelines may need Esc pressed several times 


'''Toolbox (tools affect the chosen pipeline)'''

After opening the Toolbox window you can add extra Tools (.ptool) for the pipelines like keyboard(virtual), midimonitor, quick patch, transpose, triad, (un)quantize, feedback in/out, velocity etc
 right mouse -&gt; Toolbox menu option -&gt; Install Tool... and navigate to Tool drawer (folder) and select requried .ptool 

Accompany B tool to get some sort of rythmic accompaniment, Rythm Section and Groove Quantize are examples of other tools that make use of rythms
[https://aminet.net/search?query=bars Bars &amp; Pipes pattern format .ptrn] for drawer (folder). Load from the Menu as Track or Group 


'''Accessories (affect the whole app)''' 

Accessories -&gt; Install... and goto the Accessories drawer for .paccess like adding ARexx scripting support 


'''Song Construction'''
&lt;pre&gt;
F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Duplicator 
F5  Eraser 
F6  Toolpad 
F7  Bounding box 
F8  Lock to A-B-A 

A-B-A strip, section, edit flags, white boxes, 

&lt;/pre&gt;


Bars&amp;Pipes Professional offers three track formats; basic song tracks, linear tracks — which don't loop — and finally real‑time tracks. The difference between them is that both song and linear tracks respond to tempo changes, while real‑time tracks use absolute timing, always trigger at the same instant regardless of tempo alterations 

'''Tempo Map'''

F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Eraser 
F5  Curve 
F6  Toolpad 


Compositions

Lyrics, Key, Rhythm, Time Signature 

'''Master Parameters'''

Key, Scale/Mode

'''Track Parameters'''

Dynamics 


'''Time-line Scoring'''


'''Media Madness'''


'''Mix Maestro'''


*ACCESSORIES         Allows the importation of other packages and additional modules 
*CLIPBOARD           Full cut, copy and paste operations, enabling user‑definable clips to be shared between tracks.
*INFORMATION         A complete rundown on the state of the current production and your machine.
*MASTER PARAMETERS   Enables global definition of time signatures, lyrics, scales, chords, dynamics and rhythm changes.
*MEDIA MADNESS       A complete multimedia sequencer which allows samples, stills, animation, etc 
*METRONOME           Tempo feedback via MIDI, internal Amiga audio and colour cycling — all three can be mixed and matched as required.
*MIX MAESTRO         Completely automated mixdown with control for both volume and pan. All fader alterations are memorised by the software 
*RECORD ACTIVATION   Complete specification of the data to be recorded/merged. Allows overdubbing of pitch‑bend, program changes, modulation etc
*SET FLAGS           Numeric positioning of location and edit flags in either SMPTE or musical time 
*SONG CONSTRUCTION   Large‑scale cut and paste of individual measures, verses or chorus, by means of bounding box and drag‑n‑drop mouse selections
*TEMPO MAP           Tempo change using a variety of linear and non‑linear transition curves 
*TEMPO PALETTE       Instant tempo changes courtesy of four user‑definable settings.
*TIMELINE SCORING    Sequencing of a selection of songs over a defined period — ideal for planning an entire set for a live performance.
*TOOLBOX             Selection screen for the hundreds of signal‑processing tools available 
*TRACKS              Opens the main track window to enable recording, editing and the use of tools.
*TRANSPORT           Main playback control window, which also provides access to user‑ defined flags, loop and punch‑in record modes.


Bars and Pipes Pro 2.5 is using internal 4-Byte IDs, to check which kind of data are currently processed.
Especially in all its files the IDs play an important role. The IDs are stored into the file in the same order they are laid out in the memory.

In a Bars 'N' Pipes file (no matter which kind) the ID &quot;NAME&quot; (saved as its ANSI-values) is stored on a big endian system (68k-computer) as &quot;NAME&quot;. On a little endian system (x86 PC computer) as &quot;EMAN&quot;.  The target is to make the AROS-BnP compatible to songs, which were stored on a 68k computer (AMIGA).

If possible, setting MIDI channels for Local Control for your keyboard 

http://www.fromwithin.com/liquidmidi/archive.shtml


MIDI files are essentially a stream of event data. An event can be many things, but typically &quot;note on&quot;, &quot;note off&quot;, &quot;program change&quot;, &quot;controller change&quot;, or messages that instruct a MIDI compatible synth how to play a given bit of music.

* Channel     - 1 to 16 -
* Messages    - PC presets, CC effects like delays, reverbs,  etc 
* Sequencing  - MIDI instruments, Drums, Sound design, 
* Recording   - 
* GUI         - Piano roll or Tracker, Staves and Notes 

MIDI events/messages like step entry e.g. Note On, Note Off 

MIDI events/messages like PB, PC, CC, Mono and Poly After-Touch, Sysex, etc 

MIDI sync - Midi Clocks (SPS Measures), Midi Time Code (h, m, s and frames) SMPTE 

Individual track editing with audition edits so easier to test any changes. Possible to stop track playback, mix clips from the right edit flag and scroll the display using arrow keys. 

Step entry, to extend a selected note hit the space bar and the note grows accordingly. Ability to cancel mouse‑driven edits by simply clicking the right mouse button — at which point everything snaps back into its original form. Lyrics can now be put in with syllable dividers, even across an entire measure or section. Autoranging when you open a edit window, the notes are automatically displayed — working from the lowest upwards. 

Flag editing, shift‑click on a flag immediately open the bounds window, ready for numeric input. Ability to cancel edits using the right‑hand mouse button, plus much improved Bounding Box operations.

Icons other than the BarsnPipes icon -&gt; PUBSCREEN=BarsnPipes (cannot choose modes higher than 8bit 256 colors)

Preferences -&gt; Menu in Tracks window - Send MIDI defaults OFF 

Prefs -&gt; Environment -&gt; screenmode (saved to BarsnPipes.prefs binary file) 

Customization -&gt; pics in gui drawer (folder) - 


Can save as .song files and .mid General Midi 

SMF is a “Standard Midi File”  ([http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html SMF0, SMF1 and SMF2]), [https://github.com/stump/libsmf libsmf], [https://github.com/markc/midicomp MIDIcomp], [https://github.com/MajicDesigns/MD_MIDIFile C++ src], [], [https://github.com/newdigate/midi-smf-reader Midi player], 

* SMF0        All MIDI data is stored in one track only, separated exclusively by the MIDI channel.
* SMF1        The MIDI data is stored in separate tracks/channels.
* SMF2 (rarely used) The MIDI data is stored in separate tracks, which are additionally wrapped in containers, so it's possible to have e.g. several tracks using the same MIDI channels.


Would it be possible to enrich Bars N’Pipes with software synth and sample support along with audio recording and mastering tools like in the named MAC or PC music sequencers?
On the classic AMIGA-OS this is not possible because of missing CPU-power. The hardware of the classic AMIGA is not further developed. So we must say (unfortunately) that those dreams can’t become reality

BarsnPipes is best used with external MIDI-equipment. This can be a keyboard or synthesizer with MIDI-connectors. 

&lt;pre&gt;
MIDI can control 16 channels 
There are USB-MIDI-Interfaces on the market with 16 independent MIDI-lines (multi-port), which can handle 16 MIDI devices independently – 16×16 = 256 independent MIDI-channels or instruments 
handle up to 16 different USB-MIDI-Interfaces (multi-device). That is: 16X16X16 = 4096 independent MIDI-channels – theoretically 
&lt;/pre&gt;

&lt;pre&gt;
Librarian MIDI SYStem EXplorer (sysex) - PatchEditor and used to be supplied as a separate program like PatchMeister but currently not at present 
It should support MIDI.library (PD), BlueRibbon.library (B&amp;P), TriplePlayPlus, and CAMD.library (DeluxeMusic) and 
MIDI information from a device's user manual and configure a custom interface to access parameters for all MIDI products connected to the system 
Supports ALL MIDI events and the Patch/Librarian data is stored in MIDI standard format 
Annette M.Crowling, Missing Link Software, Inc.
&lt;/pre&gt;


Composers
&lt;pre&gt;
[https://x.com/hirasawa/status/1403686519899054086 Susumu Hirasawa] 

&lt;/pre&gt;


&lt;pre&gt;
1988 Todor Fay and his wife Melissa Jordan Gray, who founded the Blue Ribbon Inc
1992 Bars&amp;Pipes Pro published 
November 2000, Todor Fay announcement to release the sourcecode of Bars&amp;Pipes Pro 2.5c beta
end of May 2001, the source of the main program and the sources of some tools and accessories were in a complete and compileable state 
end of October 2009 stop further development of BarsnPipes New for now on all supported systems and made freeware 
2013 Alfred Faust diagnosed with incureable illness, called „Myastenia gravis“ (weak muscles) 
&lt;/pre&gt;


 Protrekkr

How to use Midi In/Out in Protrekkr ?

First of all, midi in &amp; out capabilities of this program are rather limited.

# Go to Misc. Setup section and select a midi in or out device to use (ptk only supports one device at a time).
# Go to instrument section, and select a MIDI PRG (the default is N/A, which means no midi program selected).
# Go to track section and here you can assign a midi channel to each track of ptk.
# Play notes :]. Note off works. F'x' note cut command also works too, and note-volume command (speed) is supported.

Also, you can change midicontrollers in the tracker, using '90' in the panning row:

&lt;pre&gt;
    C-3 02 .. .. 0000....


    --- .. .. 90 xxyy.... &lt;&lt; This will set the value 
    --- .. .. .. 0000....    of the controller n.'xx' to 'yy' (both in hex)
    --- .. .. .. 0000....
&lt;/pre&gt;

So &quot;--- .. .. 90 2040....&quot; will set the controller number $20(32) to $40(64).

You will need the midi implementation table of your gear to know what you can change with midi controller messages.

 N.B. Not all MIDI devices are created equal!

Although the MIDI specification defines a large range of MIDI messages of various kinds, not every MIDI device is required to work in exactly the same way and respond to all the available messages and ways of working. For example, we don't expect a wind synthesiser to work in the same way as a home keyboard.

Some devices, the older ones perhaps, are only able to respond to a single channel. With some of those devices that channel can be altered from the default of 1 (probably) to another channel of the 16 possible.

Other devices, for instance monophonic synthesisers, are capable of producing just one note at a time, on one MIDI channel. Others can produce many notes spread across many channels.

Further devices can respond to, and transmit, &quot;breath controller&quot; data (MIDI controller number 2 (CC#2)) others may respond to the reception of CC#2 but not be able to create and to send it.

A controller keyboard may be capable of sending &quot;expression pedal&quot; data, but another device may not be capable of responding to that message.

Some devices just have the basic GM sound set. The &quot;voice&quot; or &quot;instrument&quot; is selected using a &quot;Program Change&quot; message on its own.

Other devices have a greater selection of voices, usually arranged in &quot;banks&quot;, and the choice of instrument is made by responding to &quot;Bank Select MSB&quot; (MIDI controller 0 (CC#0)), others use &quot;Bank Select LSB&quot; (MIDI controller number 32 (CC#32)), yet others use both MSB and LSB sent one after the other, all followed by the Program Change message. The detailed information about all the different voices will usually be available in a published MIDI Data List.


 MIDI Implementation Chart

But in the User Manual there is sometimes a summary of how the device works, in terms of MIDI, in the chart at the back of the manual, the MIDI Implementation Chart.

If you require two devices to work together you can compare the two implementation charts to see if they are &quot;compatible&quot;. In order to do this we will need to interpret that chart.

The chart is divided into four columns headed &quot;Function&quot;, &quot;Transmitted&quot; (or &quot;Tx&quot;), &quot;Received&quot; (or &quot;Rx&quot;), or more correctly &quot;Recognised&quot;, and finally, &quot;Remarks&quot;.

&lt;pre&gt;
The left hand column defines which MIDI functions are being described.
The 2nd column defines what the device in question is capable of transmitting to another device.
The 3rd column defines what the device is capable of responding to.
The 4th column is for explanations of the values contained within these previous two columns.
&lt;/pre&gt;

There should then be twelve sections, with possibly a thirteenth containing extra &quot;Notes&quot;. Finally there should be an explanation of the four MIDI &quot;modes&quot; and what the &quot;X&quot; and the &quot;O&quot; mean.
&lt;pre&gt;
Mode 1: Omni On, Poly; 
Mode 2: Omni On, Mono; 
Mode 3: Omni Off, Poly; 
Mode 4: Omni Off, Mono.
&lt;/pre&gt;
O means &quot;yes&quot; (implemented), X means &quot;no&quot; (not implemented).

Sometimes you will find a row of asterisks &quot;**************&quot;, these seem to indicate that the data is not applicable in this case. Seen in the transmitted field only (unless you've seen otherwise).

Lastly you may find against some entries an asterisk followed by a number e.g. *1, these will refer you to further information, often on a following page, giving more detail.

Basic Channel
But the very first set of boxes will tell us the &quot;Basic Channel(s)&quot; that the device sends or receives on. 
&quot;Default&quot; is what happens when the device is first turned on, &quot;changed&quot; is what a switch of some kind may allow the device to be set to. 
For many devices e.g. a GM sound module or a home keyboard, this would be 1-16 for both. That is it can handle sending and receiving on all MIDI channels.

On other devices, for example a synthesiser, it may by default only work on channel 1. But the keyboard could be &quot;split&quot; with the lower notes e.g. on channel 2. If the synth has an arppegiator, this may be able to be set to transmit and or receive on yet another channel.
So we might see the default as &quot;1&quot; but the changed as &quot;1-16&quot;.

Modes.
We need to understand Omni On and Off, and Mono and Poly, then we can decipher the four modes.

But first we need to understand that any of these four Mode messages can be sent to any MIDI channel. They don't necessarily apply to the whole device.

If we send an &quot;Omni On&quot; message (CC#125) to a MIDI channel of a device, we are, in effect, asking it to respond to e.g. a Note On / Off message pair, received on any of the sixteen channels. Sound strange? Read it again. Still strange? It certainly is. We normally want a MIDI channel to respond only to Note On / Off messages sent on that channel, not any other. In other words, &quot;Omni Off&quot;.

So &quot;Omni Off&quot; (CC#124) tells a channel of our MIDI device to respond only to messages sent on that MIDI channel.

&quot;Poly&quot; (CC#127) is for e.g. a channel of a polyphonic sound module, or a home keyboard, to be able to respond to many simultaneous Note On / Off message pairs at once and produce musical chords.

&quot;Mono&quot; (CC#126) allows us to set a channel to respond as if it were e.g. a flute or a trumpet, playing just one note at a time. If the device is capable of it, then the overlapping of notes will produce legato playing, that is the attack portion of the second note of two overlapping notes will be removed resulting in a &quot;smoother&quot; transition.

So a channel with a piano voice assigned to it will have Omni Off, Poly On (Mode 3), a channel with a saxophone voice assigned could be Omni Off, Mono On (Mode 4).

We call these combinations the four modes, 1 to 4, as defined above. 
Most modern devices will have their channels set to Mode 3 (Omni Off, Poly) but be switchable, on a per channel basis, to Mode 4 (Omni Off, Mono).

This second section of data will include first its default value i.e. upon device switch on. Then what Mode messages are acceptable, or X if none.

Finally, in the &quot;Altered&quot; field, how a Mode message that can't be implemented will be interpreted. Usually there will just be a row of asterisks effectively meaning nothing will be done if you try to switch to an unimplemented mode.

Note Number
&lt;pre&gt;
The next row will tell us which MIDI notes the device can send or receive, normally 0-127.
The second line, &quot;True Voice&quot; has the following in the MIDI specification: 
&quot;Range of received note numbers falling within the range of true notes produced by the instrument.&quot;
My interpretation is that, for instance, a MIDI piano may be capable of sending all MIDI notes (0 to 127) by transposition, but only responding to the 88 notes (21 to 108) of a real piano. 
&lt;/pre&gt;

Velocity
This will tell us whether the device we're looking at will handle note velocity, and what range from 1-127, or maybe just 64, it transmits or will recognise. So usually &quot;O&quot; plus a range or &quot;X&quot; for not implemented.

After touch
This may have one or two lines two it.
If a one liner the either &quot;O&quot; or &quot;X&quot;, yes or no.
If a two liner then it may include &quot;Keys&quot; or &quot;Poly&quot; and &quot;Channel&quot;.
This will show whether the device will respond to Polyphonic after touch or channel after touch or neither.

Pitch Bend
Again &quot;O&quot; for implemented, &quot;X&quot; for not implemented.
(Many stage pianos will have no pitch bend capability.)
It may also, in the notes section, state whether it will respond to the full 14 bits, or not, as usually encoded by the pitch bend wheel.

Control Change
This is likely to be the largest section of the chart.
It will list all those controllers, starting from CC#0, Bank Select MSB, which the device is capable of sending, and those that it will respond to using &quot;O&quot; or &quot;X&quot; respectively.
You will, almost certainly, get some further explanation of functionality in the remarks column, or in more detail elsewhere in the documentation.

Of course you will need to know what all the various controller numbers do. Lots of the official technical specifications can be found at the [www.midi.org/techspecs/ MMA], with the table of messages and control change [www.midi.org/techspecs/midimessages.php message numbers]

Program Change
Again &quot;O&quot; or &quot;X&quot; in the Transmitted or Recognised column to indicate whether or not the feature is implemented. In addition a range of numbers is shown, typically 0-127, to show what is available.
True # (number): &quot;The range of the program change numbers which correspond to the actual number of patches selected.&quot;

System Exclusive
Used to indicate whether or not the device can send or recognise System Exclusive messages. A short description is often given in the Remarks field followed by a detailed explanation elsewhere in the documentation.

System Common - These include the following:
&lt;pre&gt;
MIDI Time Code Quarter Frame messages (device synchronisation).
Song Position Pointer
Song Select
Tune Request
&lt;/pre&gt;
The section will indicate whether or not the device can send or respond to any of these messages.

System Real Time
These include the following:
&lt;pre&gt;
Timing Clock - often just written as &quot;Clock&quot;
Start
Stop
Continue
&lt;/pre&gt;
These three are usually just referred to as &quot;Commands&quot; and listed.
Again the section will indicate which, if any, of these messages the device can send or respond to.
&lt;pre&gt;
Aux. Messages
Again &quot;O&quot; or &quot;X&quot; for implemented or not.
Aux. = Auxiliary.
Active Sense = Active Sensing.
&lt;/pre&gt;
Often with an explanation of the action of the device.

Notes
The &quot;Notes&quot; section can contain any additional comments to clarify the particular implementation.

Some of the explanations have been drawn directly from the MMA MIDI 1.0 Detailed Specification.
And the detailed explanation of some of the functions will be found there, or in the General MIDI System Level 1 or General MIDI System Level 2 documents also published by the MMA.


 OFFICIAL MIDI SPECIFICATIONS

SUMMARY OF MIDI MESSAGES
Table 1 - Summary of MIDI Messages

The following table lists the major MIDI messages in numerical (binary) order (adapted from &quot;MIDI by the Numbers&quot; by D. Valenti, Electronic Musician 2/88, and updated by the MIDI Manufacturers Association.). This table is intended as an overview of MIDI, and is by no means complete.

WARNING! Details about implementing these messages can dramatically impact compatibility with other products. We strongly recommend consulting the official MIDI Specifications for additional information.

MIDI 1.0 Specification

Message Summary Channel Voice Messages [nnnn = 0-15 (MIDI Channel Number 1-16)]

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1000nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note Off event. 
This message is sent when a note is released (ended). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1001nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note On event. 
This message is sent when a note is depressed (start). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1010nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Polyphonic Key Pressure (Aftertouch). 
This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. (kkkkkkk) is the key (note) number. (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Control Change. 
This message is sent when a controller value changes. Controllers include devices such as pedals and levers. Controller numbers 120-127 are reserved as &quot;Channel Mode Messages&quot; (below). (ccccccc) is the controller number (0-119). (vvvvvvv) is the controller value (0-127).
|-
|&lt;!--Status--&gt;1100nnnn || &lt;!--Data--&gt;0ppppppp || &lt;!--Description--&gt;Program Change. This message sent when the patch number changes. (ppppppp) is the new program number.
|-
|&lt;!--Status--&gt;1101nnnn || &lt;!--Data--&gt;0vvvvvvv || &lt;!--Description--&gt;Channel Pressure (After-touch). This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. This message is different from polyphonic after-touch. Use this message to send the single greatest pressure value (of all the current depressed keys). (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1110nnnn || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Pitch Bend Change. This message is sent to indicate a change in the pitch bender (wheel or lever, typically). The pitch bender is measured by a fourteen bit value. Center (no pitch change) is 2000H. Sensitivity is a function of the receiver, but may be set using RPN 0. (lllllll) are the least significant 7 bits. (mmmmmmm) are the most significant 7 bits.
|}

Channel Mode Messages (See also Control Change, above)

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Channel Mode Messages. 
This the same code as the Control Change (above), but implements Mode control and special message by using reserved controller numbers 120-127. The commands are:
*All Sound Off. When All Sound Off is received all oscillators will turn off, and their volume envelopes are set to zero as soon as possible c = 120, v = 0: All Sound Off
*Reset All Controllers. When Reset All Controllers is received, all controller values are reset to their default values. (See specific Recommended Practices for defaults) c = 121, v = x: Value must only be zero unless otherwise allowed in a specific Recommended Practice.
*Local Control. When Local Control is Off, all devices on a given channel will respond only to data received over MIDI. Played data, etc. will be ignored. Local Control On restores the functions of the normal controllers. 
c = 122, v = 0: Local Control Off
c = 122, v = 127: Local Control On
* All Notes Off. When an All Notes Off is received, all oscillators will turn off. 
c = 123, v = 0: All Notes Off (See text for description of actual mode commands.)
c = 124, v = 0: Omni Mode Off 
c = 125, v = 0: Omni Mode On 
c = 126, v = M: Mono Mode On (Poly Off) where M is the number of channels (Omni Off) or 0 (Omni On) 
c = 127, v = 0: Poly Mode On (Mono Off) (Note: These four messages also cause All Notes Off)
|}

System Common Messages

System Messages (0xF0)

The final status nybble is a “catch all” for data that doesn’t fit the other statuses. They all use the most significant nybble (4bits) of 0xF, with the least significant nybble indicating the specific category.

The messages are denoted when the MSB of the second nybble is 1. When that bit is a 0, the messages fall into two other subcategories.

System Common

If the MSB of the second second nybble (4 bits) is not set, this indicates a System Common message. Most of these are messages that include some additional data bytes.

System Common Messages
Type Status Byte   Number of Data Bytes      Usage 
&lt;pre&gt;
Time Code Quarter Frame	0xF1	1	Indicates timing using absolute time code, primarily for synthronization with video playback systems. A single location requires eight messages to send the location in an encoded hours:minutes:seconds:frames format*.
Song Position	0xF2	2	Instructs a sequencer to jump to a new position in the song. The data bytes form a 14-bit value that expresses the location as the number of sixteenth notes from the start of the song.
Song Select	0xF3	1	Instructs a sequencer to select a new song. The data byte indicates the song.
Undefined	0xF4	0	
Undefined	0xF5	0	
Tune Request	0xF6	0	Requests that the receiver retunes itself**.
&lt;/pre&gt;
*MIDI Time Code (MTC) is significantly complex. Please see the MIDI Specification
**While modern digital instruments are good at staying in tune, older analog synthesizers were prone to tuning drift. Some analog synthesizers had an automatic tuning operation that could be initiated with this command.


System Exclusive

If you’ve been keeping track, you’ll notice there are two status bytes not yet defined: 0xf0 and 0xf7. These are used by the System Exclusive message, often abbreviated at SysEx. SysEx provides a path to send arbitrary data over a MIDI connection. There is a group of predefined messages for complex data, like fine grained control of MIDI Time code machinery. SysEx is also used to send manufacturer defined data, such as patches, or even firmware updates.

System Exclusive messages are longer than other MIDI messages, and can be any length. The messages are of the following format:

0xF0, 0xID, 0xdd, ...... 0xF7
The message is bookended with distinct bytes.

It opens with the Start Of Exclusive (SOX) data byte, 0xF0.
The next one to three bytes after the start are an identifier.
Values from 0x01 to 0x7C are one-byte vendor IDs, assigned to manufacturers who were involved with MIDI at the beginning.
If the ID is 0x00, it’s a three-byte vendor ID - the next two bytes of the message are the value.
&lt;pre&gt;
ID 0x7D is a placeholder for non-commercial entities.
ID 0x7E indicates a predefined Non-realtime SysEx message.
ID 0x7F indicates a predefined Realtime SysEx message.
&lt;/pre&gt;
After the ID is the data payload, sent as a stream of bytes.
The transfer concludes with the End of Exclusive (EOX) byte, 0xF7.
The payload data must follow the guidelines for MIDI data bytes – the MSB must not be set, so only 7 bits per byte are actually usable. If the MSB is set, it falls into three possible scenarios.

An End of Exclusive byte marks the ordinary termination of the SysEx transfer.
System Real Time messages may occur within the transfer without interrupting it. The recipient should handle them independently of the SysEx transfer.
Other status bytes implicitly terminate the SysEx transfer and signal the start of new messages.
 Some inexpensive USB-to-MIDI interfaces aren’t capable of handling messages longer than four bytes.

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11110000 || &lt;!--Data--&gt;0iiiiiii [0iiiiiii 0iiiiiii]  0ddddddd  --- --- 0ddddddd 11110111 || &lt;!--Description--&gt;System Exclusive. 
This message type allows manufacturers to create their own messages (such as bulk dumps, patch parameters, and other non-spec data) and provides a mechanism for creating additional MIDI Specification messages. The Manufacturer's ID code (assigned by MMA or AMEI) is either 1 byte (0iiiiiii) or 3 bytes (0iiiiiii 0iiiiiii 0iiiiiii). Two of the 1 Byte IDs are reserved for extensions called Universal Exclusive Messages, which are not manufacturer-specific. If a device recognizes the ID code as its own (or as a supported Universal message) it will listen to the rest of the message (0ddddddd). Otherwise, the message will be ignored. (Note: Only Real-Time messages may be interleaved with a System Exclusive.)
|-
|&lt;!--Status--&gt;11110001 || &lt;!--Data--&gt;0nnndddd || &lt;!--Description--&gt;MIDI Time Code Quarter Frame.
nnn = Message Type
dddd = Values
|-
|&lt;!--Status--&gt;11110010 || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Song Position Pointer. 
This is an internal 14 bit register that holds the number of MIDI beats (1 beat= six MIDI clocks) since the start of the song. l is the LSB, m the MSB.
|-
|&lt;!--Status--&gt;11110011 || &lt;!--Data--&gt;0sssssss || &lt;!--Description--&gt;Song Select. 
The Song Select specifies which sequence or song is to be played.
|-
|&lt;!--Status--&gt;11110100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Tune Request. Upon receiving a Tune Request, all analog synthesizers should tune their oscillators.
|-
|&lt;!--Status--&gt;11110111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;End of Exclusive. Used to terminate a System Exclusive dump. 
|}


System Real-Time Messages

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11111000 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Timing Clock. Sent 24 times per quarter note when synchronization is required.
|-
|&lt;!--Status--&gt;11111001 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111010 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Start. Start the current sequence playing. (This message will be followed with Timing Clocks).
|-
|&lt;!--Status--&gt;11111011 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Continue. Continue at the point the sequence was Stopped.
|-
|&lt;!--Status--&gt;11111100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Stop. Stop the current sequence.
|-
|&lt;!--Status--&gt;11111101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Active Sensing. This message is intended to be sent repeatedly to tell the receiver that a connection is alive. Use of this message is optional. When initially received, the receiver will expect to receive another Active Sensing message each 300ms (max), and if it does not then it will assume that the connection has been terminated. At termination, the receiver will turn off all voices and return to normal (non- active sensing) operation. 
|-
|&lt;!--Status--&gt;11111111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Reset. Reset all receivers in the system to power-up status. This should be used sparingly, preferably under manual control. In particular, it should not be sent on power-up.
|}


Advanced Messages

Polyphonic Pressure (0xA0) and Channel Pressure (0xD0)

Some MIDI controllers include a feature known as Aftertouch. While a key is being held down, the player can press harder on the key. The controller measures this, and converts it into MIDI messages.

Aftertouch comes in two flavors, with two different status messages.

The first flavor is polyphonic aftertouch, where every key on the controller is capable of sending its own independent pressure information. The messages are of the following format:
&lt;pre&gt;
0xnc, 0xkk, 0xpp
n is the status (0xA)
c is the channel nybble
kk is the key number (0 to 127)
pp is the pressure value (0 to 127)
&lt;/pre&gt;
Polyphonic aftertouch is an uncommon feature, usually found on premium quality instruments, because every key requires a separate pressure sensor, plus the circuitry to read them all.

Much more commonly found is channel aftertouch. Instead of needing a discrete sensor per key, it uses a single, larger sensor to measure pressure on all of the keys as a group. The messages omit the key number, leaving a two-byte format
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xD)
c is the channel number
pp is the pressure value (0 to 127)
&lt;/pre&gt;

Pitch Bend (0xE0)

Many keyboards have a wheel or lever towards the left of the keys for pitch bend control. This control is usually spring-loaded, so it snaps back to the center of its range when released. This allows for both upward and downward bends.

Pitch Bend Wheel

The wheel sends pitch bend messages, of the format
&lt;pre&gt;
0xnc, 0xLL, 0xMM
n is the status (0xE)
c is the channel number
LL is the 7 least-significant bits of the value
MM is the 7 most-significant bits of the value
&lt;/pre&gt;
You’ll notice that the bender data is actually 14 bits long, transmitted as two 7-bit data bytes. This means that the recipient needs to reassemble those bytes using binary manipulation. 14 bits results in an overall range of 214, or 0 to 16,383. Because it defaults to the center of the range, the default value for the bender is halfway through that range, at 8192 (0x2000).

Control Change (0xB0)

In addition to pitch bend, MIDI has provisions for a wider range of expressive controls, sometimes known as continuous controllers, often abbreviated CC. These are transmitted by the remaining knobs and sliders on the keyboard controller shown below.


Continuous Controllers

These controls send the following message format:
&lt;pre&gt;
0xnc, 0xcc, 0xvv
n is the status (0xB)
c is the MIDI channel
cc is the controller number (0-127)
vv is the controller value (0-127)
&lt;/pre&gt;

Typically, the wheel next to the bender sends controller number one, assigned to modulation (or vibrato) depth. It is implemented by most instruments.

The remaining controller number assignments are another point of confusion. The MIDI specification was revised in version 2.0 to assign uses for many of the controllers. However, this implementation is not universal, and there are ranges of unassigned controllers.

On many modern MIDI devices, the controllers are assignable. On the controller keyboard shown in the photos, the various controls can be configured to transmit different controller numbers. Controller numbers can be mapped to particular parameters. Virtual synthesizers frequently allow the user to assign CCs to the on-screen controls. This is very flexible, but it might require configuration on both ends of the link and completely bypasses the assignments in the standard.


Program Change (0xC0)

Most synthesizers have patch storage memory, and can be told to change patches using the following command:
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xc)
c is the channel
pp is the patch number (0-127)
&lt;/pre&gt;
This allows for 128 sounds to be selected, but modern instruments contain many more than 128 patches. Controller #0 is used as an additional layer of addressing, interpreted as a “bank select” command. Selecting a sound on such an instrument might involve two messages: a bank select controller message, then a program change.

Audio &amp; Midi are not synchronized, what I can do ?
Buy a commercial software package but there is a nasty trick to synchronize both. It's a bit hardcore but works for me:

 Simply put one line down to all midi notes on your pattern (use Insert key)
 and go to 'Misc. Setup', adjust the latency and just search a value
 that will make sound sync both audio/midi.

The stock Sin/Saw/Pulse and Rnd waveforms are too simple/common, is there a way to use something more complex/rich ?
You have to ability to redirect the waveforms of the instruments through the synth pipe by selecting the &quot;wav&quot; option for the oscillator you're using for this synth instrument, samples can be used as wavetables to replace the stock signals.


Sound banks like soundfont (sf2) or Kontakt2 are not supported at the moment


====DAW Audio Evolution 4====

Audio Evolution 4 gives you unsurpassed power for digital audio recording and editing on the Amiga. The latest release focusses on time-saving non-linear and non-destructive editing, as seen on other platforms. Besides editing, Audio Evolution 4 offers a wide range of realtime effects, including compression, noise gate, delays, reverb, chorus and 3-band EQ.

Whether you put them as inserts on a channel or use them as auxillaries, the effect parameters are realtime adjustable and can be fully automated. Together with all other mixing parameters, they can even be controlled remotely, using more ergonomic MIDI hardware.

Non-linear editing on the time line, including cut, copy, paste, move, split, trim and crossfade actions

The number of tracks per project(s) is unlimited .... AHI limits you to recording only two at a time. i.e. not on 8 track sound cards like the Juli@ or Phase 88.

sample file import is limited to 16bit AIFF (not AIFC, important distinction as some files from other sources can be AIFC with aiff file extention). and 16bit WAV (pcm only)


Most apps use the Music Unit only but a few apps also use Unit (0-3) instead or as well. 
* Set up AHI prefs so that microphone is available. (Input option near the bottom)


stereo++ allows the audio piece to be placed anywhere and the left-right adjusted to sound positionally right

hifi best for music playback if driver supports this option


Load 16bit .aif .aiff only sample(s) to use not AIFC which can have the same ending. AIFF stands for Audio Interchange File Format 

 sox recital.wav recital.aiff

 sox recital.wav −b 16 recital.aiff channels 1 rate 16k fade 3 norm
 sox input.wav        output.aiff bass −b 16 rate 48k

performs the same format translation, but also applies four effects (down-mix to one channel, sample rate change, fade-in, nomalize), and stores the result at a bit-depth of 16.

 rec −c 2 radio.aiff trim 0 30:00

records half an hour of stereo audio 

 play existing-file.wav


24bit PCM WAV or AIFF do not work 

*No stream format handling. So no way to pass on an AC3 encoded stream unmodified to the digital outputs through AHI.
*No master volume handling. Each application has to set its own volume. So each driver implements its own custom driver-mixer interface for handling master volumes, mute and preamps.
*Only one output stream. So all input gets mixed into one output.
*No automatic handling of output direction based on connected cables.
*No monitor input selection. Only monitor volume control. 


select the correct input (Don't mistake enabled sound for the correct input.)
The monitor will feedback audio to the lineout and hp out no matter if you have selected the correct input to the ADC. The monitor will provide sound for any valid input. This will result in free mixing when recording from the monitor input instead of mic/line because the monitor itself will provide the hardware mixing for you. Be aware that MIC inputs will give two channel mono. Only Linein will give real stereo.

Now for the not working part. Attempt to record from linein in the AE4 record window, the right channel is noise and the left channel is distorted. Even with the recommended HIFI 16bit Stereo++ mode at 48kHz.


Channels

Monitor

Gain

Inout

Output

Advanced settings - Debugging via serial port


* Options -&gt; Soundcard In/Out
* Options -&gt; SampleRate
* Options -&gt; Preferences

F6 for Sample File List

Setting a grid is easy as is measuring the BPM by marking a section of the sample. Is your kick drum track &quot;not in time&quot; ? If so, you're stumped in AE4 as it has no fancy variable time signatures and definitely no 'track this dodgy rhythm' function like software of the nature of Logic has. So if your drum beat is freeform you will need to work in freeform mode. (Real music is free form anyway).

If the drum *is* accurate and you are just having trouble measuring the time, I usually measure over a range of bars and set the number of beats in range to say 16 as this is more accurate, Then you will need to shift the drum track to match your grid *before* applying the grid. (probably an iterative process as when the grid is active samples snap to it, and when inactive you cannot see it).

AE4 does have ARexx but the functions are more for adding samples at set offsets and starting playback / recording.


These are the usual features found in DAWs...

* Recording digital audio, midi sequencer and mixer 
* virtual VST instruments and plug-ins 
* automation, group channels, MIDI channels, FX sends and returns, audio and MIDI editors and music notation editor


* different track views 
* mixer and track layout (but not the same as below) 
* traditional two windows (track and mixer)


Mixing - mixdown

Could not figure out how to select what part I wanted to send to the aux, set it to echo and return. Pretty much the whole echo effect. Or any effect.

Take look at page17 of the manual.

When you open the EQ / Aux send popup window you will see 4 sends. Now from the menu choose the windows menu.

Menus-&gt;Windows-&gt; Aux Returns Window

or press F5

You will see a small window with 4 volume controls and an effects button for each. Click a button and add an effects to that aux channel, then set it up as desired (note the reverb effect has a special AUX setting that improves its use with the aux channel, not compulsory but highly useful). You set the amount of 'return' on the main mix in the Aux Return window, and the amount sent from each main mixer channel in the popup for that channel. Again the aux sends are &quot;prefade&quot; so the volume faders on each channel do not affect them.


Tracking


Effects - fade in

To add some echoes to some vocals, tried to add an effect on a track but did not come out. This is made more complicated as I wanted to mute a vocal but then make it echo at the muting point. Want to have one word of a vocal heard and then echoed off. But when the track is mute the echo is cancelled out.

To correctly understand what is happening here you need to study the figure at the bottom of page 15 on the manual. You will see from that that the effects are applied 'prefade' So the automation you applied will naturally mute the entire signal.

There would be a number of ways to achieve the goal,

You have three real time effects slots, one for smoothing like so

Sample -&gt; Amplify -&gt; Delay

Then automate the gain of the amplify block so that it effectively mutes the sample just before the delay at the appropriate moment, the echo effect should then be heard.

Getting the effects in the right order will require experimentation as they can only be added top down and it's not obvious which order they are applied to the signal, but there only two possibilities, so it wont take long to find out.

Using MUTE can cause clicks to the Amplify can be used to mute more smoothly so that's a secondary advantage.

Signal Processing -


Overdub

[[#top|...to the top]]

===Office===

====Spreadsheet Leu====

Support for some xlsx, and ods functions 


====Spreadsheet Ignition====

; Needs ABIv1 to be completed before more can be done

File formats supported 
* ascii #?.txt and #?.csv (single sheets with data only). 
* igs and TurboCalc(WIP) #?.tc for all sheets with data, formats and formulas.

There is '''no''' support for xls, xlsx, ods or uos ([http://en.wikipedia.org/wiki/Uniform_Office_Format Uniform Unified Office Format]) at the moment.

* Always use Esc key after editing Spreadsheet cells.
* copy/paste seems to copy the first instance only so go to Edit -&gt; Clipboard to manage the list of remembered actions. 
* Right mouse click on row (1 or 2 or 3) or column header (a or b or c)  to access optimal height or width of the row or column respectively 
* Edit -&gt; Insert -&gt; Row  seems to clear the spreadsheet or clears the rows after the inserted row until undo restores as it should be...

Change Sheet name by  Object -&gt; Sheet -&gt; Properties

Click in the cell which will contain the result, and click '''down arrow button''' to the right of the formula box at the bottom of the spreadsheet and choose the function required from the list provided. Then click on the start cell and click on the bottom right corner, a '''very''' small blob, which allows stretching a bounding box (thick grey outlines) across many cells This grey bounding box can be used to '''copy a formula''' to other cells.

Object -&gt; Cell -&gt; Properties to change cell format - Currency only covers DM and not $, Euro, Renminbi, Yen or Pound etc. 
Shift key and arrow keys selects a range of cells, so that '''formatting can be done to all highlighted cells'''. 
View -&gt; Overview then select ALL with one click (in empty cell in the top left hand corner of the sheet).

Default mode is relative cell referencing e.g. a1+a2 but absolute e.g. $a$1+$a$2 can be entered.

* #sheet-name to '''absolute''' reference another sheet-name cell unless reference() function used.

;Graphs

use shift key and arrow keys to select a bunch of cells to be graph'ed making sure that x axes represents and y axes represents

* value() - 0 value, 1 percent, 2 date, 3 time, 4 unit ...


;Dates 
* Excel starts a running count from the 1st Jan 1900 and Ignition starts from 1st Jan 1AD '''(maybe this needs to change)'''
Set formatting Object -&gt; Cell -&gt; Properties and put date in days


;Time 
Set formatting Object -&gt; Cell -&gt; Properties and put time in seconds taken


;Database (to be done by someone else)

type - standard, reference (bezug), search criterion (suchkriterium), 
* select a bunch of cells and Object -&gt; Database -&gt; Define to set Datenbank (database) and Felder (fields not sure how?) 
* Neu (new) or loschen (delete) to add/remove database headings e.g. Personal, Start Date, Finish Date (one per row?)
* Object -&gt; Database -&gt; Index to add fields (felder) like Surname, First Name, Employee ID, etc. to ?

Filtering done with dbfilter(), dbproduct() and dbposition().

Activities with dbsum(), dbaverage(), dbmin() and dbmax().

Table sorting -


;Scripts (Arexx)

;Excel(TM) to Ignition - commas ''',''' replaced by semi-colons ''';''' to separate values within functions 
*SUM(), 
*AVERAGE(), MAX(), MIN(), INT(), PRODUCT(), MEDIAN(), VAR() becomes Variance(), Percentile(),
*IF(), AND, OR, NOT 
*LEFT(), RIGHT(), MID() becomes MIDDLE(), LEN() becomes LENGTH(), 
*LOWER() becomes LOWERCASE(), UPPER() becomes UPPERCASE(),
* DATE(yyyy,mm,dd) becomes COMPUTEDATE(dd;mm;yyyy), 
*TODAY(), DAY(),WEEK(), MONTH(),=YEAR(TODAY()), 
*EOMONTH() becomes MONTHLENGTH(), 
*NOW() should be date and time becomes time only, SECOND(), MINUTE(), HOUR(),
*DBSUM() becomes DSUM(),


;Missing and possibly useful features/functions needed for ignition to have better support of Excel files 
There is no Merge and Join Text over many cells, no protect and/or freeze row or columns or books but can LOCK sheets, no define bunch of cells as a name, Macros (Arexx?), conditional formatting, no Solver, no Goal Seek, no Format Painter, no AutoFill, no AutoSum function button, no pivot tables, (30 argument limit applies to Excel)

*HLOOKUP(), VLOOKUP(), [http://production-scheduling.com/excel-index-function-most-useful/ INDEX(), MATCH()], CHOOSE(), TEXT(), 
*TRIM(), FIND(), SUBSTITUTE(), CONCATENATE() or &amp;, PROPER(), REPT(), 
*[https://acingexcel.com/excel-sumproduct-function/ SUMPRODUCT()], ROUND(), ROUNDUP(), *ROUNDDOWN(), COUNT(), COUNTA(), SUMIF(), COUNTIF(), COUNTBLANK(), TRUNC(), 
*PMT(), PV(), FV(), POWER(), SQRT(), MODE(), TRUE, FALSE, 
*MODE(), LARGE(), SMALL(), RANK(), STDEV(), 
*DCOUNT(), DCOUNTA(), WEEKDAY(),


;Excel Keyboard [http://dmcritchie.mvps.org/excel/shortx2k.htm shortcuts needed to aid usability in Ignition] 
&lt;pre&gt;
Ctrl Z - Undo

Ctrl D - Fill Down
Ctrl R - Fill right

Ctrl F - Find
Ctrl H - Replace

Ctrl 1 - Formatting of Cells
CTRL SHIFT ~ Apply General Formatting ie a number 
Ctrl ; - Todays Date 

F2 - Edit cell
F4 - toggle cell absolute / relative cell references

&lt;/pre&gt;


====Document Scanning - Scandal====

Scanner usually needs to be connected via a USB port and not via a hub or extension lead.

Check in Trident Prefs -&gt; Devices that the USB Scanner is not bound to anything (e.g. Bindings None)
If not found then reboot the computer and recheck.

Start Scandal, choose Settings from Menu strip at top of screen and in Scanner Driver choose the ?#.device of the scanner (e.g. epson2.device).

The next two boxes - leave empty as they are for morphos SCSI use only
 or put ata.device (use the selection option in bigger box below) and Unit as 0 this is needed for gt68xx

* gt68xx - no editing needed in s/gt68xx.conf but needs a firmware file that corresponds to the scanner [http://www.meier-geinitz.de/sane/gt68xx-backend/ gt68xx firmwares] in sys:s/gt68xx.
* epson2 - Need to edit the file epson2.conf in sys/s that corresponds to the scanner being used

'''Save''' the settings but do not press the Use button (aros freezes)

Back to the Picture Scan window and the right-hand sections.

Click on the '''Information''' tab and press Connect button and the scanner should now be detected.

Go next to the '''Scanner''' tab next to Information Tab should have Color, Black and White, etc. and dpi settings now. Selecting an option Color, B/W etc. can cause dpi settings corruption (especially if the settings are in one line) so set '''dpi first'''. Make sure if Preview is set or not.

In the '''Scan''' Tab, press Scan and the scanner will do its duty. 
Be aware that nothing is saved to disk yet.

In the Save tab, change format JPEG, PNG or IFF DEEP. Tick incremental and base filename if necessary and then click the Save button. The image will now be saved to permanent storage.


The driver ignores a device if it is already bond to another USB class, rejects it from being usable. However, open Trident prefs, select your device and use the right mouse button to open. Select &quot;NONE&quot; to prevent poseidon from touching the device. Now save settings. It should always work now.

[[#top|...to the top]]

===Emulators===

==== Amiberry ====


==== Amiga Emu - Janus UAE ====

With Amibridge, AROS attempts to make the UAE emulator seem embedded within but it still is acting as an app 

There is no dynarec m68k for each hardware that Aros supports or direct patching of motorola calls to AROS hardware accelerated ones unless the emulator has that included 

Try starting Janus with a priority of -1 like this little script:
&lt;pre&gt;
cd sys:system/AmiBridge/emulator
changetaskpri -1
run janus-uae -f my_uaerc.config &gt;nil:
cd sys:prefs
endcli
&lt;/pre&gt;
This stops Janus hogging all the CPU time.


===Miscellaneous===

====Screensaver Blanker====

Most blankers on the amiga (i.e. aros) run as commodities (they are in the tools/commodities drawer). Double click on blanker.

Control is with an app called Exchange, which you need to run first (double click on app) or  run QUIET sys:tools/commodities/Exchange &gt;NIL: but subsequently can use (Cntrl Alt h).

Icon tool types (may be broken) or command line options 
&lt;pre&gt;
seconds=number 
&lt;/pre&gt;

Once the timing is right then add the following to s:icaros-sequence or s:user-startup

e.g. for 5 minutes

 run QUIET sys:tools/commodities/Blanker seconds=300 &gt;NIL:


*[http://archives.aros-exec.org/index.php?function=showfile&amp;file=graphics/screenblanker/gblanker.i386-aros.zip Garshneblanker] can make Aros unstable or slow. Certain blankers crashes in Icaros 2.0.x like Dragon, Executor.


*[ Acuario AROS version], the aquarium screen saver.

Startup: extras:acuariofv-aros/acuario

Kill: c:break name=extras:acuariofv-aros/acuario

Managed to start Acuario by the Executor blanker.

&lt;pre&gt;
cx_priority=
cx_popkey=    ie CX_POPKEY=&quot;Shift F1&quot; 
cx_popup=Yes or No

&lt;/pre&gt;


&lt;pre&gt;
 Qualifier String    Input Event Class
   ----------------    -----------------
    &quot;lshift&quot;           IEQUALIFIER_LSHIFT
    &quot;rshift&quot;           IEQUALIFIER_RSHIFT
    &quot;capslock&quot;         IEQUALIFIER_CAPSLOCK
    &quot;control&quot;          IEQUALIFIER_CONTROL
    &quot;lalt&quot;             IEQUALIFIER_LALT
    &quot;ralt&quot;             IEQUALIFIER_RALT
    &quot;lcommand&quot;         IEQUALIFIER_LCOMMAND
    &quot;rcommand&quot;         IEQUALIFIER_RCOMMAND
    &quot;numericpad&quot;       IEQUALIFIER_NUMERICPAD
    &quot;repeat&quot;           IEQUALIFIER_REPEAT
    &quot;midbutton&quot;        IEQUALIFIER_MIDBUTTON
    &quot;rbutton&quot;          IEQUALIFIER_RBUTTON
    &quot;leftbutton&quot;       IEQUALIFIER_LEFTBUTTON
    &quot;relativemouse&quot;    IEQUALIFIER_RELATIVEMOUSE
&lt;/pre&gt;


&lt;pre&gt;
    Synonym     Synonym
    String     Identifier
    -------    ----------
    &quot;shift&quot;    IXSYM_SHIFT    /* look for either shift key */
    &quot;caps&quot;     IXSYM_CAPS     /* look for either shift key or capslock */
    &quot;alt&quot;      IXSYM_ALT      /* look for either alt key */

Highmap is one of the following strings:
    &quot;space&quot;, &quot;backspace&quot;, &quot;tab&quot;, &quot;enter&quot;, &quot;return&quot;, &quot;esc&quot;, &quot;del&quot;,
    &quot;up&quot;, &quot;down&quot;, &quot;right&quot;, &quot;left&quot;, &quot;f1&quot;, &quot;f2&quot;, &quot;f3&quot;, &quot;f4&quot;, &quot;f5&quot;,
    &quot;f6&quot;, &quot;f7&quot;, &quot;f8&quot;, &quot;f9&quot;, &quot;f10&quot;, &quot;help&quot;.


&lt;/pre&gt;


[[#top|...to the top]]

==== World Construction Set WCS (Version 2.031) ====

WCS is a fractal landscape software such as Scenery Animator, Vista Pro and Panorama. Open sourced February 2022, World Construction Set [https://3dnature.com/downloads/legacy-software/ legally and for free] and [https://github.com/AlphaPixel/3DNature c source]. 

Announced August 1994 this version dates from April 1996 developed by Gary R. Huber and Chris &quot;Xenon&quot; Hanson&quot; from Questar 

&lt;pre&gt;
Assign &quot;WCSProjects:&quot; &quot;Volume:Dir/Dir/WCSProjects&quot; 
Assign &quot;WCSFrames:&quot;   &quot;Volume:Dir/Dir/WCSFrames&quot; 
&lt;/pre&gt;

&lt;pre&gt;
Load projects .proj by accessing pull down menu Project -&gt; Open then click on CanyonSunset.proj
OK to changing .par file and enlarge Status Log window to show what is happening 
Render by pull down menu Modules -&gt; Render with End equal 1 not 300 then click bottom middle button Render 
&lt;/pre&gt;

[https://www.youtube.com/watch?v=CxQDmf1ZWG0 Youtube walkthrough of above], [], [], 

Also try working with the already built file ColoDemo - Then open with the drop-down menu: Project/Open, then WCSProject:ColoDemo.proj
Which allows you to use altimetric DEM files already included and Loading scene parameters from ColoDemo.par
Once this is done, save everything with a new name to start working exclusively on your project. 
Then drop-down menu and select Save As (&quot;NewName&quot;.proj name), then drop-down menu to open parameter and select Save All ( .par name)


After launching the software, there is a the Module Control Panel composed of five icons. 
It is a dock type shortcut of the first few functions of the drop-down menu 

*Database   - Load (#?.proj), Append, Create, Edit, Save, Dir List (of WCSProject drawer), 
*Data Ops   - Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats  
*Map View   - Database file Loader leading to Map View Control with option to the Database Editor 
*Parameters - Editor for Motion, Color, Ecosystem, Clouds, Waves, management of altimeter files DEM, sclock settings etc 
*Render     - rendering terrain 

These are more in the pull down menu but not in the dock 
*Motion Editor
*Color Editor
*Ecosys Editor 


Simple minimal workflow 
*Load database (1st icon - 1st)
*Set parameters and save .par file (4th icon)
*Render scene (5th icon) 

[https://www.youtube.com/watch?v=ZbTwwR2qcc4 Youtube], [], 

&lt;pre&gt;
.proj new project name which creates a drawer of additional files 

.binary array, ascii array .xyz , z buffer, DTED .dt0, vista 1990s dem, iff  conversion 
.Obj with .elev, .frd with .hdr maps, - digital elevation model (DEM) is a 3D representation of elevation data in various formats 
USGS 7.5MinDEM, 

.par 


&lt;/pre&gt;


Since for the time being no project is loaded, a query window indicates a procedural error when clicking on the rendering icon (right end of the bar). The menu is quite traditional; it varies according to the activity of the windows. To display any altimetric file in the &quot;Mapview&quot; (third icon of the panel), There are three possibilities:

* Loading of a demonstration project.
* The import of a DEM file, followed by texturing and packaging from the &quot;Database-Editor&quot; and the &quot;Color-Editor&quot;.
* The creation of an altimetric file in WCS format, then texturing.


The altimeter file editing (display in the menu) is only made possible if the &quot;Mapview&quot; window is active.

The software is made up of many windows and won't be able to describe them all. Know that &quot;Color-Editor&quot; and the &quot;Data-Editor&quot; comprise sufficient functions for obtaining an almost real rendering quality. You have the possibility of inserting vector objects in the &quot;Data-Editor&quot; (creation of roads, railways, etc.) 


The Map View (MapView) window

*Database - Objects and Topos
*View     - Align, Center, Zoom, Pan, Move 
*Draw     - Maps and distance 
*Object   - Find, highlight, add points, conform topo, duplicate 
*Motion   - Camera, Focus, path, elevation 
*Windows  - DEM designer, Cloud (.cld) and wave (.wve) editor, 


You will notice that by selecting this window and simply moving the pointer to various points on the map you will see latitude and longitude values ​​change, along with the height.
Drop-down menu and Modules, then select MapView and change the width of the window with the map to arrange it in the best way on the screen. With the Auto button the center. Window that then displays the contents of my DEM file, in this case the Grand Canyon. MapView allows you to observe the shape of the landscape from above
 

ZOOM button

Press the Zoom button and then with the pointer position on a point on the map, press the left mouse button and then move to the opposite corner to circumscribe the chosen area and press the left mouse button again, then we will see the enlarged area selected on the map.
Would add that there is a box next to the Zoom button that allows the direct insertion of a value which, the larger it is, the smaller the magnification and the smaller the value, the stronger the magnification. At each numerical change you will need to press the DRAW button to update the view.

PAN button

Under Zoom you will find the PAN button which allows you to move the map at will in all directions by the amount you want. This is done by drawing a line in one direction, then press PAN and point to an area on the map with the pointer and press the left mouse button. At this point, leave it and move the pointer in one direction by drawing a line and press the left mouse button again to trigger the movement of the map on the screen (origin and end points). Do some experiments and then use the Auto button immediately below to recenter everything.
There are parameters such as TOPO, VEC to be left checked and immediately below one that allows different views of the map with the Style command (Single, Multi, Surface, Emboss, Slope, Contour), each with its own particularities to highlight different details.

Now you have the first basics to manage your project visually on the map. Close the MapView window and go further...


Let's start working on ECOSYSTEMS
If we select Emboss from the MapView Style command we will have a clear idea of ​​how the landscape appears, realizing that it is a predominantly desert region of our planet. Therefore we will begin to act on any vegetation present and the appearance of the landscape.
With WCS we will begin to break down the elements of the landscape by assigning defined characteristics. It will be necessary to determine the classes of the ecosystem (Class) with parameters of Elevation Line (maximum altitude), Relative Elevation (arrangement on basins or convexities with respectively positive or negative parameters), Min Slope and Max Slope (slope). WCS offers the possibility of making ecosystems coexist on the same terrain with the UnderEco function, by setting a Density value.


Ecosys Ecosystem Editor

Let's open it from Modules, then Ecosys Editor. In the left pane you will find the list of ecosystems referring to the files present in our project. It will be necessary to clean up that box to leave only the Water and Snow landscapes and a few other predefined ones. We can do this by selecting the items and pressing the Remove button (be careful not for all elements the button is activated, therefore they cannot all be eliminated).
Once this is done we can start adding new ecosystems. Scroll through the various Unused and as soon as the Name item at the top is activated allowing you to write, type the name of your ecosystem, adding the necessary parameters.
&lt;pre&gt;
Ecosystem1: Name: RockBase Class: Rock Density: 80 MinSlope: 15 UnderEco: Terrain
Ecosystem2: Name: RockIncl Clss: Rock Density: 80 MinSlope: 30 UnderEco: Terrain
Ecosystem3: Name: Grass Class Low Veg Density: 50 Height: 1 Elev Line : 1500 Rel El Eff: 5
Max Slope: 10 – Min Slope: 0 UnderEco: Terrain
Ecosistema4: Name: Shrubs Class: Low Veg Density: 40 Height: 8 Elev Line: 3000
Rel El Eff: -2 Max Slope: 20 Min Slope : 5 UnderEco: Terrain
Ecosistema5: Name: Terrain Class: Ground Density: 100 UnderEco: Terrain
&lt;/pre&gt;

Now we need to identify an intermediate ecosystem that guarantees a smooth transition between all, therefore we select as Understory Ecosystem the one called Terrain in all ecosystems, except Snow and Water .
Now we need to 'emerge' the Colorado River in the Canyon and we can do this by raising the sea level to 900 (Sea Level) in the Ecosystem called Water.
Please note that the order of the ecosystem list gives priority to those that come after. So our list must have the following order: Water, Snow, Shrubs, RockIncl, RockBase, Terrain. It is possible to carry out all movements with the Swap button at the bottom. To put order you can also press Short List. Press Keep to confirm all the work done so far with Ecosystem Editor.
Remember every now and then to save both the Project 'Modules/Save' and 'Parameter/Save All'

EcoModels are made up of .etp .fgp .iff8 for each model 


Color Editor

Now it's time to define the colors of our scene and we can do this by going to Modules and then Color Editor. In the list we focus on our ecosystems, created first.
Let's go to the bottom of the list and select the first white space, assigning the name 'empty1', with a color we like and then we will find this element again in other environments... It could serve as an example for other situations!
So we move to 'grass' which already exists and assign the following colors: R 60 G 70 B50
&lt;pre&gt;
'shrubs': R 60 G 80 B 30
'RockIncl' R 110 G 65 B 60
'RockBase' R 110 G 80 B 80
' Terrain' R 150 G 30 B 30
&lt;pre&gt;
Now we can work on pre-existing colors
&lt;pre&gt;
'SunLight' R 150 G 130 B 130
'Haze and Fog' R 190 G 170 B 170
'Horizon' R 209 G 185 B 190
'Zenith' R 140 G 150 B 200
'Water' R 90 G 125 B 170
&lt;/pre&gt;

Ambient R 0 G 0 B 0

So don't forget to close Color Editor by pressing Keep.
Go once again to Ecosystem Editor and assign the corresponding color to each environment by selecting it using the Ecosystem Color button. Press it several times until the correct one appears. Then save the project and parameters again, as done previously.


Motion Editor

Now it's time to take care of the framing, so let's go to Modules and then to Motion Editor. An extremely feature-rich window will open. Following is the list of parameters regarding the Camera, position and other characteristics:
&lt;pre&gt;
-Camera Altitude: 7.0
-Camera Latitude: 36.075
-Camera Longitude: 112.133
-Focus Attitude: -2.0
-Focus Latitude: 36.275
-Focus Longitude: 112.386
-Camera : 512 → rendering window
-Camera Y: 384 → rendering window
-View Arc: 80 → View width in degrees
-Sun Longitude: 172
-Sun Latitude: -0.9
-Haze Start: 3.8
-Haze Range: 78, 5
&lt;/pre&gt;
As soon as the values ​​shown in the relevant sliders have been modified, we will be ready to open the CamView window to observe the wireframe preview. Let's not consider all the controls that will appear.
Well from the Motion Editor if you have selected Camera Altitude and open the CamView panel, you can change the height of the camera by holding down the right mouse button and moving the mouse up and down. To update the view, press the Terrain button in the adjacent window. As soon as you are convinced of the position, confirm again with Keep. You can carry out the same work with the other functions of the camera, such as Focus Altitude...
Let's now see the next positioning step on the Camera map, but let's leave the CamView preview window open while we go to Modules to open the window at the same time MapView. We will thus be able to take advantage of the view from the other together with a subjective one.


From the MapView window, select with the left mouse button and while it is pressed, move the Camera as desired. To update the subjective preview, always click on Terrain.
While with the same procedure you can intervene on the direction of the camera lens, by selecting the cross and with the left button pressed you can choose the desired view. So with the pressure of Terrain I update the Preview. Possibly can enlarge or reduce the Map View using the Zoom button, for greater precision.
Also write that the circle around the cameras indicates the beginning of the haze, there are two types (haze and fog) linked to the altitude. Would also add that the camera height is editable through the Motion Editor panel.


The sun

Let's see that changing the position of the sun from the Motion Editor. Press the SUN button at the bottom right and set the time and the date. Longitude and latitude are automatically obtained by the program. Always open the View Arc command from the Motion Editor panel, an item present in the Parameter List box.

Once again confirm everything with Keep and then save again.


Animation

The animation part is not left-back and also occupies a window. The settings possibilities are enormous. A time line with dragging functions (&quot;slide&quot;, &quot;drag&quot;...) comparable to that of LightWave completes this window. 


A small window is available for positioning the stars as a function of a date, in order to vary the seasons and their various events (and yes...).

At the bottom of the &quot;Motion-Editor&quot;, a &quot;cam-view&quot; function will give you access to a control panel. Different preview modes are possible. The rendering is also accessible through a window. No less than nine pages compose it. At this level, you will be able to determine the backup name of your images (&quot;path&quot;), the type of texture to be calculated, the resolution of the images, activate or deactivate functions such as the depth buffer (&quot;zbuffer&quot;), the blur, the background image, etc.


Once all these parameters have been set, all you have to do is click on the &quot;Render&quot; button.

For rendering go to Modules and then Render. Select the resolution, then under IMA select the name of the image. Move to FRA and indicate the level of fractal detail which of 4 is quite good. Then Keep to confirm and then reopen the window, pressing Render you will see the result. The image will be opened with any viewing program.


Strengths:

* Multi-window.
* Quality of rendering.
* Accuracy.
* Opening, preview and rendering on CyberGraphX screen.
* Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats 
* The &quot;zbuffer&quot; function.

Weaknesses:

* No OpenGL management 
* Calculation time.
* No network computing tool.


====Writing CD / DVD - Frying Pan====

Can be backup DVDs (4GB ISO size limit due to use of FileInfoBlock), create audio cds from mp3's, and put .iso files on discs

If using for the first time - click Drive button and Device set to ata.device and unit to 0 (zero)

Click Tracks Button - Drive 1 - Create New Disc or Import Existing Disc Image (iso bin/cue etc.) - Session File open cue file

If you're making a data cd, with files and drawers from your hard drive, you should be using the ISO Builder.. which is the MUI page on the left. (&quot;Data/Audio Tracks&quot; is on the right).

You should use the &quot;Data/Audio tracks&quot; page if you want to create music cds with AIFF/WAV/MP3 files, or if you download an .iso file, and you want to put it on a cd.

Click WRITE Button - set write speed - click on long Write button

Examples

Easiest way would be to burn a DATA CD, simply go to &quot;Tracks&quot; page &quot;ISO Builder&quot; and &quot;ADD&quot; everything you need to burn.

On the &quot;Write&quot; page i have &quot;Masterize Disc (DAO)&quot;, &quot;Close Disc&quot; and &quot;Eject after Write&quot; set.

One must not &quot;Blank disc before write&quot; if one uses a CDR


AUDIO CD from MP3's are as easy but tricky to deal with. FP only understands one MP3 format, Layer II, everything else will just create empty tracks

Burning bootable CD's works only with .iso files. Go to &quot;Tracks&quot; page and &quot;Data/Audio Tracks&quot; and add the .iso


====odf====

Every ODF file is a collection of several subdocuments within a package (ZIP file), each of which stores part of the complete document.

* content.xml – Document content and automatic styles used in the content.
* styles.xml – Styles used in the document content and automatic styles used in the styles themselves.
* meta.xml – Document meta information, such as the author or the time of the last save action.
* settings.xml – Application-specific settings, such as the window size or printer information.


To read document follow these steps:

* Extracting .ods file.
* Getting content.xml file (which contains sheets data).
* Creating XmlDocument object from content.xml file.
* Creating DataSet (that represent Spreadsheet file).
* With XmlDocument select “table:table” elements, and then create adequate DataTables.
* Parse child’s of “table:table” element and fill DataTables with those data.
* At the end, return DataSet and show it in application’s interface.


To write document follow these steps:

* Extracting template.ods file (.ods file that we use as template).
* Getting content.xml file.
* Creating XmlDocument object from content.xml file.
* Erasing all “table:table” elements from the content.xml file.
* Reading data from our DataSet and composing adequate “table:table” elements.
* Adding “table:table” elements to content.xml file.
* Zipping that file as new .ods file.

XLS file format

The XLS file format contains streams, substreams, and records.

These sheet substreams include worksheets, macro sheets, chart sheets, dialog sheets, and VBA module sheets. 
All the records in an XLS document start with a 2-byte unsigned integer to specify Record Type (rt), and another for Count of Bytes (cb). A record cannot exceed 8224 bytes. If larger than the rest is stored in one or more continue records.

* Workbook stream 
**Globals substream
***BoundSheet8 record - info for Worksheet substream i.e. name, location, type, and visibility. (4bytes the lbPlyPos FilePointer, specifies the position in the Workbook stream where the sheet substream starts) 
**Worksheet substream (sheet) - Cell Table - Row record - Cells (2byte=row 2byte=column 2byte=XF format)
***Blank cell record
***RK cell record 32-bit number. 
***BoolErr cell record (2-byte Bes structure that may be either a Boolean value or an error code)
***Number cell record (64-bit floating-point number)
***LabelSst cell record (4-byte integer that specifies a string in the Shared Strings Table (SST). Specifically, the integer corresponds to the array index in the RGB field of the SST)
***Formula cell record (FormulaValue structure in the 8 bytes that follow the cell structure. The next 6 bytes can be ignored, and the rest of the record is a CellParsedFormula structure that contains the formula itself)
***MulBlank record (first 2 bytes give the row, and the next 2 bytes give the column that the series of blanks starts at. Next, a variable length array of cell structures follows to store formatting information, and the last 2 bytes show what column the series of blanks ends on)
***MulRK record 
***Shared String Table (SST) contains all of the string values in the workbook.

ACCRINT(), ACCRINTM(), AMORDEGRC(), AMORLINC(), 
COUPDAYBS(), COUPDAYS(), COUPDAYSNC(), COUPNCD(), COUPNUM(), COUPPCD(), 
CUMIPMT(), CUMPRINC(), 
DB(), DDB(), DISC(), 
DOLLARDE(), DOLLARFR(), 
DURATION(), EFFECT(), FV(), FVSCHEDULE(), 
INTRATE(), IPMT(), IRR(), ISPMT(), MDURATION(), MIRR(), NOMINAL(), NPER(), NPV(), 
ODDFPRICE(), ODDFYIELD(), ODDLPRICE(), ODDLYIELD(), 
PMT(), PPMT(), PRICE(), PRICEDISC(), PRICEMAT(), PV(), RATE(), 
RECEIVED(), SLN(), SYD(), TBILLEQ(), TBILLPRICE(), TBILLYIELD(), 
VDB(), XIRR(), XNPV(), YIELD(), YIELDDISC(), YIELDMAT(),


&lt;pre&gt;
&lt;/pre&gt;


&lt;pre&gt;
&lt;/pre&gt;

&lt;pre&gt;
&lt;/pre&gt;

{{BookCat}}</text>
      <sha1>0xt9ri5q5d9p9dt65isf8h12ojyq1bw</sha1>
    </revision>
    <revision>
      <id>4669880</id>
      <parentid>4669845</parentid>
      <timestamp>2026-09-13T10:27:09Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669880</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="240457" sha1="n9w4pd14ox4cmtqm1eqytaex5mz3d35" xml:space="preserve">
==Introduction==


[[#Graphical Image Editing Art]]
[[#Office Application]]
[[#Audio]]

[[#Misc Application]]
[[#Games &amp; Emulation]]

[[#Application Guides]]

[[#top|...to the top]]


[[#top|...to the top]]

Most apps can be opened on the Workbench (aka publicscreen pubscreen) which is the default display option but can offer a custom one set to your configurations (aka custom screen mode promotion). These custom ones tend to stack so the possible use of A-M/A-N method of switching between full screens and the ability to pull down screens as well 

If you are interested in creating or porting new software, see [http://en.wikibooks.org/wiki/Aros/Developer/Docs here]

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Internet Applications 
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Web Online Browser [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=network/browser/ Amelinium], Odyssey 2.0, [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1175&amp;highlight=odyssey&amp;rowstart=100 Odyssey 3.0], [], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/comm/www Amelinium], [https://blog.alb42.de/programs/amifox/ amifox] with [https://github.com/alb42/wrp wrp server], IBrowse*, Voyager*, [https://github.com/amigazen/aweb3/ AWeb 3.6 src], [https://github.com/matjam/aweb AWeb Src], [http://aminet.net/package/comm/www/NetSurf-m68k-sources Netsurf], [], 
|&lt;!--AmigaOS4--&gt;[ Odyssey OWB], [ Timberwolf (Firefox port 2011)], [http://amigaworld.net/modules/newbb/viewtopic.php?forum=32&amp;topic_id=32847 OWB-mui], [http://strohmayer.org/owb/ OWB-Reaction], IBrowse*, [http://os4depot.net/index.php?function=showfile&amp;file=network/browser/aweb.lha AWeb], Voyager, [http://www.os4depot.net/index.php?function=browse&amp;cat=network/browser Netsurf], 
|&lt;!--MorphOS--&gt;Wayfarer, [http://fabportnawak.free.fr/owb/ Odyssey OWB], [ Netsurf], IBrowse*, AWeb, [], 
|-
|&lt;!--Sub Menu--&gt;YouTube, Dailymotion website downloading videos audio [https://github.com/yt-dlp/yt-dlp yt-dlp], [https://clipgrab.org/ clipgrab],  
|&lt;!--AROS--&gt;[], [https://blog.alb42.de/amitube/ Amitube], 
|&lt;!--Amiga OS--&gt;[https://blog.alb42.de/amitube/ Amitube], [ smtube], 
|&lt;!--AmigaOS4--&gt;[https://blog.alb42.de/amitube/ Amitube], getVideo, Tubexx, [https://github.com/walkero-gr/aiostreams aiostreams], 
|&lt;!--MorphOS--&gt;[ ytsearch], [https://blog.alb42.de/amitube/ Amitube], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 getVideo], Tubexx 
|-
|&lt;!--Sub Menu--&gt;Old style E-mailing SMTP POP3 IMAP based 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/email SimpleMail], [http://sourceforge.net/projects/simplemail/files/ src], [https://github.com/jens-maus/yam YAM] 
|&lt;!--Amiga OS--&gt;[http://sourceforge.net/projects/simplemail/files/ SimpleMail], [https://github.com/jens-maus/yam YAM]
|&lt;!--AmigaOS4--&gt;SimpleMail, YAM, 
|&lt;!--MorphOS--&gt; SimpleMail, YAM
|-
|&lt;!--Sub Menu--&gt;IRC, ICB, 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat WookieChat], [https://sourceforge.net/projects/wookiechat/ Wookiechat src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat AiRcOS], Jabberwocky, 
|&lt;!--Amiga OS--&gt;Wookiechat, AmIRC 
|&lt;!--AmigaOS4--&gt;Wookiechat 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=5 Wookiechat], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 AmIRC], 
|-
|&lt;!--Sub Menu--&gt;Instant Messaging IM like [https://github.com/BlitterStudio/amidon Hollywood lang based Mastodon client], BlueSky AT protocol, Facebook(TM), Twitter X (TM), Bitlbee IRC Gateway and others 
|&lt;!--AROS--&gt;[https://github.com/kaffeine1/telegram-amiga telegram-amiga], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat jabberwocky], 
|&lt;!--Amiga OS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], CLIMM, SabreMSN, jabberwocky, 
|&lt;!--AmigaOS4--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], SabreMSN,
|&lt;!--MorphOS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 PolyglotNG], SabreMSN,
|-
|&lt;!--Sub Menu--&gt;Torrents 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/p2p ArTorr], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;CTorrent, Transmission 
|&lt;!--MorphOS--&gt;MLDonkey, Beehive, [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Transmission], CTorrent, 
|-
|&lt;!--Sub Menu--&gt;FTP 
|&lt;!--AROS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], MarranoFTP, 
|&lt;!--Amiga OS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://aminet.net/package/comm/tcp/AmiFTP AmiFTP], AmiTradeCenter, ncFTP, 
|&lt;!--AmigaOS4--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|&lt;!--MorphOS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Pftp], [http://aminet.net/package/comm/tcp/AmiFTP-1.935-OS4 AmiFTP], 
|-
|&lt;!--Sub Menu--&gt;WYSIWYG Web Site Editor
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Internet Radio Streaming Audio [http://www.gnu.org/software/gnump3d/ gnump3d], [http://www.icecast.org/ Icecast2] Server (Broadcast) and Client (Listen), [ mpd], [http://darkice.sourceforge.net/ DarkIce], [http://www.dyne.org/software/muse/ Muse], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc], Mplayer (Icecast Client only), 
|&lt;!--Amiga OS--&gt;[https://github.com/sandlbn/TuneFinder TuneFinder C Src], [https://github.com/sandlbn/TuneFinderMUI TuneFinderMUI], [http://amigazeux.net/anr/ AmiNetRadio], [], [], 
|&lt;!--AmigaOS4--&gt;[http://www.tunenet.co.uk/ Tunenet], 
|&lt;!--MorphOS--&gt;Mplayer, AmiNetRadio, 
|-
|&lt;!--Sub Menu--&gt;VoIP (Voice over IP) with SIP Client (Session Initiation Protocol) or Asterisk IAX2 Clients Softphone (skype like) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;AmiPhone with Speak Freely, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Weather Forecast 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ WeatherBar], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench AWeather], []
|&lt;!--Amiga OS--&gt;[http://amigazeux.net/wetter/ Wetter], [https://github.com/emartisoft/AmiWeatherForecasts AmiWeatherForecasts src], 
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/?function=showfile&amp;file=utility/workbench/flipclock.lha FlipClock], 
|&lt;!--MorphOS--&gt;[http://amigazeux.net/wetter/ Wetter], 
|-
|&lt;!--Sub Menu--&gt;Street Road Maps Route Planning GPS Tracking  
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/muimapparium/ MuiMapparium] [https://build.alb42.de/ Build of MuiMapp versions], 
|&lt;!--Amiga OS--&gt;AmiAtlas*, UKRoutePlus*, [http://blog.alb42.de/ AmOSM], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://blog.alb42.de/programs/mapparium/ Mapparium], 
|-
|&lt;!--Sub Menu--&gt;Clock and Date setting from the internet (either ntp or websites) [https://www.timeanddate.com/worldclock/ World Clock], [http://www.time.gov/ NIST], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc ntpsync],  
|&lt;!--Amiga OS--&gt;ntpsync 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Newsgroups
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[http://newscoaster.sourceforge.net/ Newscoaster], [https://github.com/jens-maus/newsrog NewsRog], [ WorldNews], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;RSS 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/Team-Boingo/AmiRSS AmiRSS src]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;AI
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/murinsel/AmigaAI Claude], [https://github.com/geekychris/amiga_mcp AI on host machine], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BBS
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Graphical Image Editing Art==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Image Editing
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Pixel Raster Artwork [https://github.com/LibreSprite/LibreSprite LibreSprite based on GPL aseprite], [https://github.com/abetusk/hsvhero hsvhero], [], 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/ZunePaint/ ZunePaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit LunaPaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit GrafX2], [ LodePaint needs OpenGL], 
|&lt;!--Amiga OS--&gt;[http://www.amigaforever.com/classic/download.html PPaint], GrafX2, [https://github.com/grovdata/Amiga_Sources/blob/master/software.md DeluxePaint], [http://www.amiforce.de/perfectpaint/perfectpaint.php PerfectPaint], Zoetrope, Brilliance2*, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit LodePaint], GrafX2, 
|&lt;!--MorphOS--&gt;Sketch, Pixel*, GrafX2, [http://morphos.lukysoft.cz/en/vypis.php?kat=3 LunaPaint]
|-
|&lt;!--Sub Menu--&gt;Image viewing 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LookHere], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LoView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer PicShow] , [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--Amiga OS--&gt;PicShow, PicView, Photoalbum,
|&lt;!--AmigaOS4--&gt;WarpView, PicShow, flPhoto, Thumbs, [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album]
|-
|&lt;!--Sub Menu--&gt;Photography retouching / Image Manipulation like Photoshop(tm)  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOEffects], 
|&lt;!--Amiga OS--&gt;[ Tecsoft Video Paint aka TVPaint], Photogenics*, ArtEffect*, ImageFX*, XiPaint, fxPaint, ImageMasterRT, Opalpaint, 
|&lt;!--AmigaOS4--&gt;WarpView, flPhoto, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit Photocrop]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], ImageFX*, 
|-
|&lt;!--Sub Menu--&gt;Manage RAW picture folder galleries like Darktable, RAWtherapy, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Graphic Format Converter - ICC profile support sRGB, Adobe RGB, XYZ and linear RGB 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;GraphicsConverter, ImageStudio, [http://www.coplabs.org/artpro.html ArtPro]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Thumbnail Generator [], 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/shell Thumbnail Generator]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Icon Editor
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/iconedit Archives], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench Icon Toolbox], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/iconedit IconEditor]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Pixel Art Animation 
|&lt;!--AROS--&gt;Lunapaint
|&lt;!--Amiga OS--&gt;PPaint, AnimatED, Scala*, GoldDisk MovieSetter*, Walt Disney's Animation Studio*, ProDAD*, [https://github.com/historicalsource/DeluxePaint DeluxePaint src], Brilliance
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 Titler] 
|-
|&lt;!--Sub Menu--&gt;2D SVG based MovieSetter type 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;MovieSetter*, Fantavision*
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Morphing 
|&lt;!--AROS--&gt;[ GLMorph]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Cad (qcad-&gt;LibreCAD, etc.) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Xcad, MaxonCAD
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Cad like FreeCad, BRL-CAD, OpenSCAD, AvoCADo, etc. using dxf, obj (vertices), blend, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;XCad3d*, DynaCADD*, Cycas, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Model Rendering of glft (json) gbl (png jpg), usdz (USD files with materials, textures, and animations), FBX Filmbox is a proprietary Autodesk format, 
|&lt;!--AROS--&gt;POV-Ray
|&lt;!--Amiga OS--&gt;[http://www.discreetfx.com./amigaproducts.html CINEMA 4D]*, POV-Ray, Lightwave3D*, Real3D*, Caligari24*, Reflections/Monzoom*, [https://github.com/privatosan/RayStorm Raystorm src], Tornado 3D
|&lt;!--AmigaOS4--&gt;Blender, POV-Ray, Yafray
|&lt;!--MorphOS--&gt;Blender, POV-Ray, Yafray
|-
|&lt;!--Sub Menu--&gt;3D Format Converter [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=graphics/convert/ 3doc.i386-aros], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=showfile&amp;file=graphics/convert/ivcon.lha IVCon]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen grabbing display 
|&lt;!--AROS--&gt;[ Screengrabber], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc snapit], [http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record screen recorder], []
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Grab graphics music from apps [https://github.com/Malvineous/ripper6 ripper6], [],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Office Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Office
!width:10%;|AROS (x86)
!width:10%;|[http://en.wikipedia.org/wiki/Amiga_software Commodore-Amiga OS 3.1] (68k)
!width:10%;|[http://en.wikipedia.org/wiki/AmigaOS_4 Hyperion OS4] (PPC)
!width:10%;|[http://en.wikipedia.org/wiki/MorphOS MorphOS] (PPC)
|-
|&lt;!--Sub Menu--&gt;Office Suite 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[ Softwood Final Office], [ Wordworth Office], [ Digita Office],  [ The Works!], [ Europress Mini Office], [], [ Papyrus Office Demo], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Word-processing 
|&lt;!--AROS--&gt;[https://finalwriter.godaddysites.com/ Final Writer 7*], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1995&amp;rowstart=20&amp;pid=12668#post_12668 Slovo], [https://github.com/sodero/MUI-Vim/releases MUI-Vim], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/wordprocessing Cinnamon Writer], [], 
|&lt;!--AmigaOS--&gt;[ Softwood FinalCopy II*], Haage AmigaWriter*, Digita WordWorth*, Softwood FinalWriter*, Micro-Systems Excellence 3*, Arnor Protext, Rashumon, [ InterWord], [ KindWords], [WordPerfect], [ New Horizons Flow], [ CygnusEd Pro], [ Micro-systems Scribble], 
|&lt;!--AmigaOS4--&gt;AbiWord, [ CinnamonWriter], 
|&lt;!--MorphOS--&gt;[ Cinnamon Writer], [http://www.meta-morphos.org/viewtopic.php?topic=1246&amp;forum=53 scriba], [http://morphos.lukysoft.cz/en/index.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Spreadsheets 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/leu/ Leu], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/spreadsheet ], 
|&lt;!--AmigaOS--&gt;[https://aminet.net/package/biz/spread/ignition-src Ignition Src 1.3], [MaxiPlan 500 Plus], [OXXI Plan/IT v2.0 Speadsheet], [ Superplan], [ Creative Developments TurboCalc], [ ProCalc], [ InterSpread], [Digita DGCalc], [ Gold Disk Advantage], [ Micro-systems Analyze!]
|&lt;!--AmigaOS4--&gt;Gnumeric, [https://ignition-amiga.sourceforge.net/ Ignition], 
|&lt;!--MorphOS--&gt;[ ignition], [http://morphos.lukysoft.cz/en/vypis.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Presentations
|&lt;!--AROS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, 
|&lt;!--Amiga OS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, MediaPoint, PointRider, Scala*, 
|&lt;!--Amiga OS4--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider 
|&lt;!--MorphOS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider
|-
|&lt;!--Sub Menu--&gt;Databases 
|&lt;!--AROS--&gt;[http://sdb.freeforums.org/ SDB], [http://archives.arosworld.org/index.php?function=browse&amp;cat=office/database BeeBase], 
|&lt;!--Amiga OS--&gt;Precision Superbase 4 Pro*, Arnor Prodata*, BeeBase, Datastore, FinalData*, AmigaBase, Fiasco, Twist2*, [Digita DGBase], [], 
|&lt;!--AmigaOS4--&gt;BeeBase, SQLite, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=6 BeeBase], 
|-
|&lt;!--Sub Menu--&gt;PDF Viewing and editing digital signatures 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/arospdf/ ArosPDF via splash], [https://github.com/wattoc/AROS-vpdf vpdf wip], 
|&lt;!--Amiga OS--&gt;APDF 
|&lt;!--AmigaOS4--&gt;AmiPDF 
|&lt;!--MorphOS--&gt;APDF, vPDF, 
|-
|&lt;!--Sub Menu--&gt;Note Taking markdown support like Obsidian like, joplin, OneNote, EverNotes, xournalpp, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Study and analyse, collect, organize, annotate, cite, and share
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PIM Personal Information Manager - Day Diary Planner Calendar App 
|&lt;!--AROS--&gt;[ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;Digita Organiser*, On The Ball, Everyday Organiser, [ Contact Manager], 
|&lt;!--AmigaOS4--&gt;AOrganiser, 
|&lt;!--MorphOS--&gt;[http://polymere.free.fr/orga_en.html PolyOrga], 
|-
|&lt;!--Sub Menu--&gt;Accounting
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=office/misc ETB], LoanCalc, [ ], [ ], [ ], 
|[ Digita Home Accounts2], Accountant, Small Business Accounts, Account Master, [ Amigabok], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Project Management Research 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;SuperGantt, SuperPlan, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Desktop 
|&lt;!--AROS--&gt;Wanderer, Scalos, Workbook, DOpus5, 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://github.com/zapek/Ambient Ambient Src]
|-
|&lt;!--Sub Menu--&gt;System Wide Search 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool Finder], [], [], 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Wide Dictionary - multilingual [http://sourceforge.net/projects/babiloo/ Babiloo], [http://code.google.com/p/stardict-3/ StarDict], 
|&lt;!--AROS--&gt;[ ],  
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System wide Thesaurus - multi lingual
|&lt;!--AROS--&gt;[ ], 
|Kuma K-Roget*, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Sticky Desktop Notes (post it type) 
|&lt;!--AROS--&gt;[http://aminet.net/package/util/wb/amimemos.i386-aros AmiMemos], [https://aminet.net/package/util/wb/amimemos.src-aros AmiMemos Src], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/util/wb/StickIt-2.00 StickIt v2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DTP Desktop Publishing 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOPublisher], 
|&lt;!--Amiga OS--&gt;[http://pagestream.org/ Pagestream]*, Professional Pro Page*, Saxon Publisher, Pagesetter, PenPal, 
|&lt;!--AmigaOS4--&gt;[http://pagestream.org/ Pagestream]* 
|&lt;!--MorphOS--&gt;[http://pagestream.org/ Pagestream]* 
|-
|&lt;!--Sub Menu--&gt;Printing 
|&lt;!--AROS--&gt;Postscript 3 laser printers, [https://github.com/bohunamiga/MintPRINT MintPRINT AirPrint IPP], [ Ghostscript], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/boingball/MintPRINT MintPRINT IPP], [https://github.com/Andiweli/AmiAirprint AmiAirprint], [http://www.irseesoft.de/tp_what.htm TurboPrint]*, [ GutenPrint], [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], [], [], 
|&lt;!--AmigaOS4--&gt;(some native drivers), 
|&lt;!--MorphOS--&gt;early TurboPrint included, [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], 
|-
|&lt;!--Sub Menu--&gt;Scanning 
|&lt;!--AROS--&gt;[ SCANdal], [], 
|&lt;!--Amiga OS--&gt;FxScan*, ScanQuix* 
|&lt;!--AmigaOS4--&gt;SCANdal (Sane)
|&lt;!--MorphOS--&gt;SCANdal
|-
|&lt;!--Sub Menu--&gt;OCR
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/convert gOCR] 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos-files.net/categories/office/text Tesseract] 
|-
|&lt;!--Sub Menu--&gt;Text Editing
|&lt;!--AROS--&gt;Jano Editor (already installed as Editor), [http://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit EdiSyn], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Vim], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd] [https://github.com/vidarh/FrexxEd src], [ NoWinEd], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/text/edit/TurboText20 TurboText20 ttx], Annotate, MicroGoldED/CubicIDE*, CygnusED*, Protext*, NoWinED, 
|&lt;!--AmigaOS4--&gt;Notepad, Annotate, CygnusED*, NoWinED, 
|&lt;!--MorphOS--&gt;MorphOS ED, NoWinED, GoldED/CubicIDE*, CygnusED*, Annotate, 
|-
|&lt;!--Sub Menu--&gt;Office Fonts [http://sourceforge.net/projects/fontforge/files/fontforge-source/ Font Designer] 
|&lt;!--AROS--&gt;[ ], [ ], 
|&lt;!--Amiga OS--&gt;TypeSmith*, SaxonScript (GetFont Adobe Type 1), 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Drawing Vector
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/amifig/ ZuneFIG previously AmiFIG], [https://github.com/serk118/designworks-aros designworks aros 64bit]
|&lt;!--Amiga OS--&gt;Drawstudio*, ProVector*, ArtExpression*, Professional Draw*, AmiFIG, MetaView, [https://gitlab.com/amigasourcecodepreservation/designworks Design Works Src], [], 
|&lt;!--AmigaOS4--&gt;MindSpace, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit amifig], 
|&lt;!--MorphOS--&gt;SteamDraw, [http://aminet.net/package/gfx/edit/amifig amiFIG], 
|-
|&lt;!--Sub Menu--&gt;video conferencing (jitsi) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;source code hosting
|&lt;!--AROS--&gt;Gitlab, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (server)
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/VNC_Server ArosVNCServer], 
|&lt;!--Amiga OS--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC], [http://dspach.free.fr/amiga/avnc/index.html AVNC]
|&lt;!--AmigaOS4--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC] 
|MorphVNC, vncserver
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (client) login and connect to another machine 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/VNC_Client/ ArosVNC], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc rdesktop], 
|&lt;!--Amiga OS--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://dspach.free.fr/amiga/vva/index.html VVA], [http://www.hd-zone.com/ RDesktop]
|&lt;!--AmigaOS4--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|-
|&lt;!--Sub Menu--&gt;notifications 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Ranchero 
|&lt;!--AmigaOS4--&gt;Ringhio 
|&lt;!--MorphOS--&gt;MagicBeacon 
|-
|&lt;!--Sub Menu--&gt;Biometric facial logins and fingerprint security features 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Audio==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Audio
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing playback Audio like MP3, [https://github.com/chrg127/gmplayer NSF], [https://github.com/kode54/lazyusf miniusf .usflib] [https://gitlab.com/kode54/psflib with pfslib], [], [], etc 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ HarmonyPlayer hp], [http://www.a500.org/downloads/audio/index.xhtml playcdda] CDs, [ WildMidi Player], [https://bszili.morphos.me/ UADE mod player], [], [ RNOTunes], [ mp3Player], [], 
|&lt;!--Amiga OS--&gt;AmiNetRadio, AmigaAmp, playOGG, [https://codeberg.org/tygre/amimodradio amimodradio]
|&lt;!--AmigaOS4--&gt;TuneNet, SimplePlay, AmigaAmp, TKPlayer
|AmiNetRadio, Mplayer, Kaya, AmigaAmp
|-
|&lt;!--Sub Menu--&gt;Editing Audio 
|&lt;!--AROS--&gt;[ Audio Evolution 4] 
|&lt;!--Amiga OS--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec Src], [http://www.sonicpulse.de/eng/news.html SoundFX], [ Samplitude], 
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec], AmiSoundED, [http://os4depot.net/?function=showfile&amp;file=audio/record/audioevolution4.lha Audio Evolution 4] 
|[http://www.hd-rec.de/HD-Rec/index.php?site=home HD-Rec], 
|-
|&lt;!--Sub Menu--&gt;Editing Tracker Music
|&lt;!--AROS--&gt;[https://github.com/hitchhikr/protrekkr Protrekkr], [ Schism Tracker], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/tracker MilkyTracker], [http://www.hivelytracker.com/ HivelyTracker], [ Radium in AROS already],  [http://www.a500.org/downloads/development/index.xhtml libMikMod], 
|&lt;!--Amiga OS--&gt;MilkyTracker, HivelyTracker, DigiBooster, Octamed SoundStudio, [https://github.com/elindstrom/soundtracker soundtracker], 
|&lt;!--AmigaOS4--&gt;MilkyTracker, HivelyTracker, GoatTracker
|MilkyTracker, GoatTracker, DigiBooster, 
|-
|&lt;!--Sub Menu--&gt;Editing Music [], [https://github.com/kmatheussen/camd CAMD] and/or staves and musical notes on manuscript 
|&lt;!--AROS--&gt;[http://bnp.hansfaust.de/ Bars and Pipes], [], [], 
|&lt;!--Amiga OS--&gt;[http://bnp.hansfaust.de/ Bars'n'Pipes], MusicX* David &quot;Talin&quot; Joiner &amp; Craig Weeks (for Notator-X), Deluxe Music Construction Set DMCS2*, [https://github.com/timoinutilis/midi-sequencer-amigaos Horny c Src] [https://github.com/kas1e/midi-sequencer-amigaos/tree/master/HornyGCC HornyGCC OS4 src] [https://github.com/capehill/midi-sequencer-amigaos Horny OS4 fork src] [https://www.amigans.net/modules/newbb/viewtopic.php?start=0&amp;topic_id=8143&amp;order=ASC&amp;status=&amp;mode=0 OS4 thread], HD-Rec, [https://aminet.net/package/mus/midi/dominatorV1_51 Dominator], [https://github.com/royaltm/Amiga-midiIn Amiga-midiIn]
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Rockbeat, [http://bnp.hansfaust.de/download.html Bars'n'Pipes], [https://github.com/gooofy/freeaction Horny OS4 src fork], Audio Evolution 4, 
|&lt;!--MorphOS--&gt;Bars'n'Pipes, 
|-
|&lt;!--Sub Menu--&gt;Sound Sampling 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/record Audio Evolution 4], [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;did=162 Quick Record], [https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc SOX to get AIFF 16bit files], [https://github.com/aros-development-team/AROS/tree/master/workbench/tools/AHIRecord AHIRecord], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/mus/edit/AudioEvolution3_src Audio Evolution 3 c src], [ Samplitude]*, Audiomaster IV*, 
|&lt;!--AmigaOS4--&gt;[https://github.com/timoinutilis/phonolith-amigaos phonolith c src], HD-Rec, Audio Evolution 4,
|&lt;!--MorphOS--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Audio Evolution 4,
|-
|&lt;!--Sub Menu--&gt;Audio Processing like easyeffects so having limiter, compressor, convolver, equalizer and auto volume and many other plugins 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Live Looping or Audio Misc - Groovebox like
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;CD/DVD burn
|[https://code.google.com/p/amiga-fryingpan/ FryingPan], 
|&lt;!--Amiga OS--&gt;FryingPan, [http://www.estamos.de/makecd/#CurrentVersion MakeCD], 
|&lt;!--AmigaOS4--&gt;FryingPan, AmiDVD, 
|[http://www.amiga.org/forums/printthread.php?t=58736 FryingPan], Jalopeano, 
|-
|&lt;!--Sub Menu--&gt;CD/DVD audio rip
|Lame, [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;cfid=0&amp;did=167 Quick CDrip],
|&lt;!--Amiga OS--&gt;Lame,  
|&lt;!--AmigaOS4--&gt;Lame, 
|Lame,  
|-
|&lt;!--Sub Menu--&gt;MP3 v1 and v2 Tagger
|&lt;!--AROS--&gt;id3ren (v1), [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/edit mp3info], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|
|-
|&lt;!--Sub Menu--&gt;Audio Convert
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc Sox], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/mus/misc/SoundBox SoundBox], [http://aminet.net/package/mus/misc/SoundBoxKey SoundBox Key], [http://aminet.net/package/mus/edit/SampleE SampleE], sox 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DJ mixing jamming 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/djh0ffman/PT1210 Hoffman PT1210 DJ tracker], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Radio Automation Software [http://www.rivendellaudio.org/ Rivendell], [http://code.campware.org/projects/livesupport/report/3 Campware LiveSupport], [http://www.sourcefabric.org/en/airtime/ SourceFabric AirTime], [http://www.ohloh.net/p/mediabox404 MediaBox404], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speakers Audio Sonos Mains AC networked wired controlled 
*2005 ZP100 with ZP80 
*2008 Zoneplayer ZP120 (multi-room wireless amp)  ZP90 receiver only with CR100 controller, 
*2009 ZonePlayer S5, 
*2010 BR100 wireless Bridge (no support),   
*2011 Play:3
*2013 Bridge (no support), Play:1,  
*2016 Arc,   Play:1,   
*Beam (Gen 2),   Playbar,  Ray,   Era 100,   Era 300,   Roam,   Move 2,   
*Sub (Gen 3),   Sub Mini,  Five,  Amp  S2 
|&lt;!--AROS--&gt;SonosController 
|&lt;!--Amiga OS--&gt;SonosController
|&lt;!--AmigaOS4--&gt;SonosController
|&lt;!--MorphOS--&gt;SonosController
|-
|&lt;!--Sub Menu--&gt;Smart Speakers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Video Creativity and Production==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Video
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing Video 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ VAMP], [http://www.a500.org/downloads/video/index.xhtml CDXL player], [http://www.a500.org/downloads/video/index.xhtml IffAnimPlay], [], 
|&lt;!--Amiga OS--&gt;Frogger*, AMP2, MPlayer, RiVA*, MooViD*, 
|&lt;!--AmigaOS4--&gt;DvPlayer, MPlayer 
|&lt;!--MorphOS--&gt;MPlayer, Frogger, AMP2, VLC 
|-
|&lt;!--Sub Menu--&gt;Streaming Video and game streaming like OBS studio, Parsec, [https://github.com/lizardbyte/sunshine sunshine], [https://github.com/moonlight-stream/moonlight-qt moonlight], etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Playing DVD 
|&lt;!--AROS--&gt;[http://a-mc.biz/ AMC]*, Mplayer 
|&lt;!--Amiga OS--&gt;AMP2, Frogger 
|&lt;!--AmigaOS4--&gt;[http://a-mc.biz/ AMC]*, DvPlayer*, AMP2,  
|&lt;!--MorphOS--&gt;Mplayer 
|-
|&lt;!--Sub Menu--&gt;Screen Recording
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record Screenrecorder], [ ], [ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Screenrecorder, 
|-
|&lt;!--Sub Menu--&gt;Create Edit Individual Video - Amiga like OSs have no pro NLE 
|&lt;!--AROS--&gt;[ Mencoder], [ Quick Videos], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit AVIbuild], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc FrameBuild], FFMPEG, 
|&lt;!--Amiga OS--&gt;[ MainConcept Mainactor Broadcast*], [http://en.wikipedia.org/wiki/Video_Toaster Video Toaster*], MacroSystem MovieShop 4.3*, proDAD Adorage*, [ IOSpirit VHI studio]*, [Gold Disk ShowMaker], [], 
|&lt;!--AmigaOS4--&gt;FFMpeg/GUI 
|&lt;!--MorphOS--&gt;Blender, Mencoder, FFmpeg
|-
|&lt;!--Sub Menu--&gt;Subtitle editor 
|&lt;!--AROS--&gt;[https://aminet.net/package/text/edit/Slarti_Arosx86ABIv0 Slarti_Arosx86ABIv0], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;IP-based video production workflows with High Dynamic Range (HDR), 10-bit color collaborative NDI, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Blogging like Lemmy or kbin
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR face recognition for Vtubers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting Live2D models with Cubism type editor or [https://github.com/AyagamiDev/ayagami ayagami] like with zipped moc3 with model metadata (model3, cdi3) 
&lt;pre&gt;
Model data (cmo3)
Basic motions (can3)
Background image (png)
Set of files for embedding (runtime folder)
• Model data (moc3)
• Motion data (motion3.json)
• Model settings file (model3.json)
• Physics settings file (physics3.json)
• Display auxiliary file (cdi3.json)
&lt;/pre&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting chatters .VRML models - standardized 3D file format for VR avatars 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;V-tubers V-tubing like Vseeface with Openseeface tracker or Vpuppr (virtual puppet project) for online live 2d / 3d art models rigging rigged LIV 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]


==Misc Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;File Management 
|&lt;!--AROS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 DOpus Magellan aka DOpus 5], [ Scalos], [ ], 
|&lt;!--Amiga OS--&gt;DOpus2, DOpus 4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], ClassAction, FileMaster, [http://www.amiga.org/forums/showthread.php?t=4897 DirWork 2]*, [https://github.com/RudolphRiedel/DiskMaster2 DiskMaster2 src], 
|&lt;!--AmigaOS4--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], Filer, AmiDisk 
|&lt;!--MorphOS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|-
|&lt;!--Sub Menu--&gt;File Verification / Repair 
|&lt;!--AROS--&gt;[https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility md5sum], [https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility/filetool asum], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool workpar2] (PAR2),  [http://zakalwe.fi/~shd/foss/cksfv/files/ compile cksfv from website], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Par2, 
|-
|Application Installer 
|&lt;!--AROS--&gt;[], [ InstallerNG], 
|&lt;!--Amiga OS--&gt;InstallerNG, Grunch, 
|&lt;!--AmigaOS4--&gt;Jack
|&lt;!--MorphOS--&gt;Jack 
|-
|&lt;!--Sub Menu--&gt;Compression archiver [https://github.com/FS-make-simple/paq9a paq9a], [], 
|&lt;!--AROS--&gt;XAD system is a toolkit designed for handling various file and disk archiver
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[https://aminet.net/package/util/pack/decrunchmania_os4 Crunchmania CrM2 depacker], 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Binary Hexadecimal Editor 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Zaphod], [],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Partition Editor formatter Disk Management
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1440&amp;highlight=partition&amp;pid=8821#post_8821 QuickPart], [ HDToolBox]
|&lt;!--Amiga OS--&gt;[https://github.com/stefanskotte/hdpart hdpart], [https://github.com/ChuckyGang/AmiPart AmiPart], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Repair and backups 
|&lt;!--AROS--&gt;ArSFSDoctor, 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/disk/bakup/quarterback_src Quarterback Tools C and asm src], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Disk check, integrity and history [https://github.com/smartmontools/smartmontools smart tools], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Multiple File renaming
|&lt;!--AROS--&gt;DOpus 4 or 5, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Anti Virus
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;VChecker, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Random Wallpaper Desktop changer [ DOpus5], [ Scalos],  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Alarm Clock, Timer, Stopwatch, Countdown 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench DClock], [http://aminet.net/util/time/AlarmClockAROS.lha AlarmClock], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 2==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;C/C++ IDE Integrated Development 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/aidea/ AIDEa], [ Murks], [],  
|&lt;!--Amiga OS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, [ StormC], [https://github.com/jens-maus/amide amide], [], 
|&lt;!--AmigaOS4--&gt;CodeBench , [https://gitlab.com/boemann/codecraft CodeCraft], 
|&lt;!--MorphOS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, 
|-
|&lt;!--Sub Menu--&gt;C/C++ Text Editors 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd], [https://github.com/vidarh/FrexxEd FrexxEd src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate] with [https://www.onyxsoft.se/files/annotate_src.lha src], 
|&lt;!--Amiga OS--&gt;[ Protext], [ CED], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://www.onyxsoft.se/annotate.html Annotate], 
|-
|&lt;!--Sub Menu--&gt;Repository
|&lt;!--AROS--&gt;[ Git]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;Git
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BASIC Computer Language 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Basic4SDL], [ Ace Basic], [ X-AMOS], [SDLBasic], [ Alvyn], 
|&lt;!--Amiga OS--&gt;[http://www.amiforce.de/main.php Amiblitz 3] with [https://github.com/AmiBlitz/AmiBlitz3 Asm src], [http://amos.condor.serverpro3.com/AmosProManual/contents/c1.html Amos Pro] with [https://github.com/AmiDARK/AmosProfessionalUnity-Official-Releases Asm src], [http://aminet.net/package/dev/basic/ace24dist ACE Basic], [https://github.com/gooofy/aqb aqb], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;sdlBasic
|-
|&lt;!--Sub Menu--&gt;Computer Languages Translation [https://tetracorp.github.io/guide/reverse-engineering-amiga.html], [https://amigasourcecodepreservation.gitlab.io/amiga-assembler-insider-guide/], [https://github.com/kermitfrog/Amiga-Re-Engineering Rust, Ghidra and FS-UAE], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://bitbucket.org/rhinoid/convert68000toc/src/main/ convert m68k seka asm-one to c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Gui Creators
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/guitool MuiBuilder], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ MuiBuilder],  
|-
|&lt;!--Sub Menu--&gt;Catalog .cd .ct Custom App Language Editors 
|&lt;!--AROS--&gt;FlexCat, [https://archives.arosworld.org/index.php?function=browse&amp;cat=utility Flexcat GUI], [], 
|&lt;!--Amiga OS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|&lt;!--AmigaOS4--&gt;[http://aminet.net/package/dev/misc/simplecat SimpleCat], FlexCat
|&lt;!--MorphOS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|-
|&lt;!--Sub Menu--&gt;Cross Development 
|&lt;!--AROS--&gt;[], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/geekychris/amiga_mcp amiga_mcp], [https://github.com/mbergmann-sh/AmigaED4-IDE AmigaED4-IDE], [https://lemonspawn.com/turbo-rascal-syntax-error-expected-but-begin/ Turbo Rascal], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Misc Application 3==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;System 
|&lt;!--AROS--&gt;[ SysExplorer], [ SysMon], [ Scout], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Terminals Shells CLIs 
|&lt;!--AROS--&gt;[https://tomaszstaniak.com/aros-term/ aros-term], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;OSK On Screen Keyboard
|&lt;!--AROS--&gt;[], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/util/wb/OSK.lha OSK]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Magnifier Magnifying Glass Magnification 
|&lt;!--AROS--&gt;[http://www.onyxsoft.se/files/zoomit.lha ZoomIT], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Comic Book CBR CBZ format reader viewer 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comics], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comicon], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Reader 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#legadon Legadon EPUB],[]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Converter 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Text to Speech tts [https://github.com/JonathanFly/bark-installer Bark], [], 
|&lt;!--AROS--&gt;[ Echo &quot; &quot; &gt;SPEAK:A1 inbuilt], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc flite], 
|&lt;!--Amiga OS--&gt;[http://www.text2speech.com translator], [https://github.com/sidick/narrator.wyoming narrator.wyoming], [], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=search&amp;tool=simple FLite]
|&lt;!--MorphOS--&gt;[http://se.aminet.net/pub/aminet/mus/misc/ FLite]
|-
|&lt;!--Sub Menu--&gt;Speech Voice Recognition Dictation - [http://sourceforge.net/projects/cmusphinx/files/ CMU Sphinx], [http://julius.sourceforge.jp/en_index.php?q=en/index.html Julius], [http://www.isip.piconepress.com/projects/speech/index.html ISIP], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speech Voice Changer [], [], [], [], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Display Blanker screensaver 
|&lt;!--AROS--&gt;Blanker Commodity (built in), [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/screenblanker GarshneBlanker], [http://sourceforge.net/projects/gblanker/ GBlanker Src], [], 
|&lt;!--Amiga OS--&gt;MultiCX, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;ModernArt Blanker, 
|-
|&lt;!--Sub Menu--&gt;Fortune Cookie Quotes Sayings 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc AFortune], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 4==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Fractals mandelbrot, etc 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc], 
|&lt;!--Amiga OS--&gt;ZoneXplorer, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Landscape Rendering 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/raytrace WCS World Construction Set], 
|&lt;!--Amiga OS--&gt;[ Vista Pro], [http://en.wikipedia.org/wiki/World_Construction_Set World Construction Set]
|&lt;!--AmigaOS4--&gt;[ WCS World Construction Set],
|&lt;!--MorphOS--&gt;[ WCS World Construction Set],
|-
|&lt;!--Sub Menu--&gt;Astronomy [https://sourceforge.net/projects/skychart/ skychart freepascal], [], [], 
|&lt;!--AROS--&gt;[ Digital Almanac (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/search?query=planetarium Aminet search], [http://aminet.net/misc/sci/DA3V56ISO.zip Digital Almanac], [https://aminet.net/package/misc/sci/da3sourceV58 Src c V58], [ Galileo renamed to Distant Suns]*, [], 
|&lt;!--AmigaOS4--&gt;[http://sourceforge.net/projects/digital-almanac/ Digital Almanac], Distant Suns*, [http://www.digitaluniverse.org.uk/ Digital Universe]*,
|&lt;!--MorphOS--&gt;[http://www.aminet.net/misc/sci/da3.lha Digital Almanac], [http://www.aminet.net/package/misc/sci/da3-mos-src Src c V56], 
|-
|&lt;!--Sub Menu--&gt;Astrology [https://sourceforge.net/projects/skylendar/ skylendar], [https://github.com/CruiserOne/Astrolog Astrolog], [https://www.astrolog.org/astrolog/astfile.htm Astrology alt site], [https://saravali.github.io/download.html Maitreya], [https://github.com/alamahant/Asteria Asteria], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Genealogy History Family Tree Ancestry Records (FreeBMD, FreeREG, and FreeCEN file formats or GEDCOM GenTree)
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; [ Origins], [ Your Family Tree], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Languages 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Fun School, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;https://github.com/evil4dmin/ami2ha
|-
|&lt;!--Sub Menu--&gt;Mathematics ([http://www-fourier.ujf-grenoble.fr/~parisse/install_en.html Xcas], etc.), 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/scientific mathX] 
|&lt;!--Amiga OS--&gt;Maple V, mathX, Fun School, GCSE Maths, [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;Yacas 
|&lt;!--MorphOS--&gt;Yacas 
|-
|&lt;!--Sub Menu--&gt;Maths Graph Function Plotting
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#MUIPlot MUIPlot], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;App Utility Launcher Dock toolbar  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/docky BoingBar], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/adkennan/DockBot Dockbot],
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Printer [https://github.com/OrcaSlicer/OrcaSlicer OrcaSlicer]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PCB design
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Digital Signage
|&lt;!--AROS--&gt;Hollywood, Hollywood Designer 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;HAM radio, amateur radio, packet radio,  [], [], [], [https://cemaxecuter.com/ Dragon OS], [https://github.com/km4ack/73Linux with 73 link update], [https://www.youtube.com/watch?v=YAL5KNePRSg video for], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/punktniklas/NiKom NiKom], [https://www.amigarealm.com/amiga/amicomms/comm4.htm Comm4], [https://www.amigarealm.com/archives/comms/aarug/ TNC Terminal Node Controller with packets over serial connections on Yaesu or Woxum handheld], [https://aminet.net/comm/misc AmiCom], [ with 7Plus file encoder/decoder], [ mksstv], [ RTTYam], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;modern smart-home network like Home Assistant, Mosquitto, EMQX,  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/evil4dmin/ami2ha HA], [https://github.com/sidick/midge mtqq.lib], [https://aminet.net/package/comm/tcp/AmiHomeassist-0.7 AmiHomeassist], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Teaching classroom learning training [https://github.com/moodle/moodle moodle], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Games &amp; Emulation==

Some emulators/games require OpenGL to function and to adjust ahi prefs channels, frequency and unit0 and unit1 and 
[http://aros.sourceforge.net/documentation/users/shell/changetaskpri.php changetaskpri -1]

Rom patching  https://www.marcrobledo.com/RomPatcher.js/ https://www.romhacking.net/patch/ (ips, ups, bps, etc) and this other site supports the latter formats https://hack64.net/tools/patcher.php 

Free public domain roms for use with emulators can be found [http://www.pdroms.de/ here] as most of the rest are covered by copyright rules. If you like to read about old games see [http://retrogamingtimes.com/ here] and [http://www.armchairarcade.com/neo/ here] and a [http://www.vintagecomputing.com/ blog] about old computers. Possibly some of the [http://www.answers.com/topic/list-of-best-selling-computer-and-video-games best selling] of all time. [http://en.wikipedia.org/wiki/List_of_computer_system_emulators Wiki] with emulated systems list.

[https://archive.gamehistory.org/ Archive of VGHF], [https://library.gamehistory.org/ Video Game History Foundation Library search]


{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Emulation]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Games Emulation Amstrad CPC 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [ Caprice32 (OpenGL &amp; pure SDL)], [ Arnold], [https://retroshowcase.gr/cpcbox-master/], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Apple2 and 2GS
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Arcade 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Mame], [ SI Emu (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;Mame, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem xmame], amiarcadia, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 Mame], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 2600 [], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Stella], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 5200 [https://github.com/wavemotion-dave/A5200DS A5200DS], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 7800
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 400 800 130XL [https://github.com/wavemotion-dave/A8DS A8DS], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Atari800], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Lynx
|&lt;!--AROS--&gt;[http://myfreefilehosting.com/f/6366e11bdf_1.93MB Handy (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Jaguar
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Bandai Wonderswan 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation BBC Micro and Acorn Electron [http://beehttps://bem-unix.bbcmicro.com/download.html BeebEm], [http://b-em.bbcmicro.com/ B-Em], [http://elkulator.acornelectron.co.uk/ Elkulator], [http://electrem.emuunlim.com/ ElectrEm], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Dragon 32 and Tandy CoCo [http://www.6809.org.uk/xroar/ xroar], [], 
|&lt;!--AROS--&gt;[], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C16 Plus4
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C64
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Vice (ABIv0 only)], [], 
|&lt;!--Amiga OS--&gt;Frodo, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem viceplus], 
|&lt;!--MorphOS--&gt;Vice, 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore Amiga
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Janus UAE], Emumiga, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer UAE], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 UAE], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Japanese MSX MSX2 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Intelivision
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Colecovision and Adam
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Milton Bradley (MB) Vectrex [ Vectrex OpenGL], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation PICO8 Pico-8 fantasy video game console [https://github.com/egordorichev/pemsa-sdl/ pemsa-sdl], [https://github.com/jtothebell/fake-08 fake-08], [https://github.com/Epicpkmn11/fake-08/tree/wip fake-08 fork], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo Gameboy
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem vba no sound], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem vba]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo NES
|&lt;!--AROS--&gt;[ EmiNES], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Fceu], [https://github.com/takahirox/nes-js?tab=readme-ov-file nes-js], [https://github.com/bfirsh/jsnes jsnes], [https://github.com/angelo-wf/NesJs NesJs], 
|&lt;!--Amiga OS--&gt;AmiNES, [http://www.dridus.com/~nyef/darcnes/ darcNES], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem amines]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo SNES
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Zsnes], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem warpsnes]
|&lt;!--MorphOS--&gt;[http://fabportnawak.free.fr/snes/ Snes9x], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo N64 
*HLE and plugins [ mupen64], [https://github.com/ares-emulator/ares ares], [https://github.com/N64Recomp/N64Recomp N64Recomp], [https://github.com/rt64/rt64 rt64], [https://github.com/simple64/simple64 Simple64], 
*LLE [], 
|&lt;!--AROS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+],
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+], [http://aminet.net/package/misc/emu/tr-981125_src TR64], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Gamecube Wii]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Wii U]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/yuzu-emu Nintendo Switch]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation NEC PC Engine 
|&lt;!--AROS--&gt;[], [], [https://github.com/yhzmr442/jspce js-pce], 
|[http://www.hugo.fr.fm/ Hugo], [http://mednafen.sourceforge.net/ Mednafen], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem tgemu]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Master System (SMS)
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Dega], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem sms], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem osmose]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Genesis/Megadrive
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem gp no sound], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem DGen], 
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/genplus-gx/ Genplus], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem genesisplus]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Saturn 
*HLE [https://mednafen.github.io/ mednafen], [http://yabause.org/ yabause], [], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;[http://yabause.org/ Yabause], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Dreamcast 
*HLE [https://github.com/flyinghead/flycast  flycast], [https://code.google.com/archive/p/nulldc/downloads NullDC], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair ZX80 and ZX81 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair Spectrum 
|[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Fuse (crackly sound)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer SimCoupe], [ FBZX slow], [https://jsspeccy.zxdemo.org/ jsspeccy], [http://torinak.com/qaop/games qaop], 
|&lt;!--Amiga OS--&gt;[http://www.lasernet.plus.com/ Asp], [http://www.zophar.net/sinclair.html Speculator], [http://www.worldofspectrum.org/x128/index.html X128], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair QL
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/QDOS4amiga1 QDOS4amiga]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation SNK NeoGeo Pocket
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem gngeo], NeoPop, 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sony PlayStation
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem FPSE], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem FPSE]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS2]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS3]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://vita3k.org/ Sony Vita]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/shadps4-emu/shadPS4 PS4]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation [http://en.wikipedia.org/wiki/Tangerine_Computer_Systems Tangerine] Oric and Atmos 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Oricutron]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem Oricutron]
|&lt;!--MorphOS--&gt;[http://aminet.net/package/misc/emu/oricutron Oricutron]
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 99/4 99/4A [https://github.com/wavemotion-dave/DS994a DS994a], [], [https://js99er.net/#/ js99er], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/TI4Amiga TI4Amiga], [http://aminet.net/package/misc/emu/TI4Amiga_src TI4Amiga src in c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation HP 38G 40GS 48 49G/50G Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 58 83 84 85 86 - 89 92 Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [https://www.rockpapershotgun.com/ General]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|- style=&quot;background:lightgrey;{{text default color}}; text-align:center; font-weight:bold;&quot;
| Games [https://www.trackawesomelist.com/michelpereira/awesome-open-source-games/ Open Source and others] || AROS || Amiga OS || Amiga OS4 || Morphos 
|-
|&lt;!--Sub Menu--&gt;Games Action like [https://github.com/opentomb/OpenTomb opentomb], [https://github.com/LostArtefacts/TRX TRX formerly Tomb1Main], [https://github.com/TombEngine TombEngine], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Thrust], [https://github.com/fragglet/sdl-sopwith sdl sopwith], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action BOH], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/BSzili/OpenLara/tree/amiga/src source of openlara SDL2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Adventure like [http://dotg.sourceforge.net/ DMJ], [https://github.com/kromenak/gengine Gabriel Knight 3], [http://www.sarien.net/ Sierra Sarien], [https://github.com/klembot/twinejs twine js], [https://github.com/QSPFoundation/qspgui Quest Soft Player QSP], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/adventure dmagnetic], [https://archives.arosworld.org/?function=browse&amp;cat=emulation/misc ScummVM], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying frotz infocom], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Board like [https://github.com/aperture-software/colditz-escape escape from colditz], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/board], [http://amigan.1emu.net/releases Africa]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Cards 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/card], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12934#post_12934 Balatro], 
|&lt;!--AmigaOS--&gt;[http://home.arcor.de/amigasolitaire/e/welcome.html Reko], [https://github.com/samskivert/beschei-en beschei Src], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Misc [https://github.com/michelpereira/awesome-open-source-games Awesome open], [https://github.com/bobeff/open-source-games General Open Source], [https://github.com/SAT-R/sa2 Sonic Advance 2], [https://github.com/velorek1/cwordle Wordle type], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games FPS like [https://aminet.net/package/game/shoot/D1X_Rebirth_AGA Descent D1X src], [https://github.com/DescentDevelopers/Descent3 Descent 3], [https://github.com/Fewnity/Counter-Strike-Nintendo-DS Counter-Strike-Nintendo-DS], [https://github.com/Aleph-One-Marathon/alephone Bungie Marathon 1994], [https://zdoom.org/downloads UzDoom opengl 3.3], [https://github.com/ZDoom/gzdoom gzdoom opengl 3+], [https://zdoom.org/downloads LZDoom opengl 2.1], 
|&lt;!--AROS--&gt;Doom, Quake, [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Quake 3 Arena (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Assault Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube 2 Sauerbraten (OpenGL)], [http://fodquake.net/test/ FodQuake QuakeWorld], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Duke Nukem 3D], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Darkplaces Nexuiz Xonotic], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Doom 3 SDL (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Hexenworld and Hexen 2], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Aliens vs Predator Gold 2000 avp (openGL)], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Odamex (openGL doom)], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ zgloom], [], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ ab3dhd], [], 
|&lt;!--Amiga OS--&gt;Doom, Quake, AB3D, Fears, Breathless, Gloom, 
|&lt;!--AmigaOS4--&gt;Doom, Quake, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12 Doom], Quake, Quake 3 Arena, [https://github.com/OpenXRay/xray-16 S.T.A.L.K.E.R Xray]
|-
|&lt;!--Sub Menu--&gt;Games MMORG like 
|&lt;!--AROS--&gt;[ Eternal Lands (OpenGL)],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Platform like 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform], [ Maze of Galious], [ Gish]*(openGL), [ Mega Mario], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ thextech SMBX], [http://www.gianas-return.de/ Giana's Return], [http://www.sqrxz.de/ Sqrxz], [www.sqrxz2.de/ Sqrxz 2], [http://www.sqrxz.de/sqrxz-3/ Sqrxz 3], [http://www.sqrxz.de/sqrxz-4/ Sqrxz 4], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform Cave Story], [https://bszili.morphos.me/ Frogatto], [https://bszili.morphos.me/ OpenJazz], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ pekkakana2], [ Aquaria], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ sonic CD], [], 
|&lt;!--Amiga OS--&gt;[ Giana Sisters], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Puzzle [https://github.com/mariopartyrd/marioparty4/tree/port Party], [https://github.com/mdodis/OpenSolomonsKey OpenSolomonsKey], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle], [ Cubosphere (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle Candy Crisis], [http://bszili.morphos.me/ TailTale], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Racing [ Trigger Rally], [ VDrift], [http://www.ultimatestunts.nl/index.php?page=2&amp;lang=en Ultimate Stunts], [http://maniadrive.raydium.org/ Mania Drive], [https://github.com/plowteam/donut Simpsons Hit and Run], [], 
|&lt;!--AROS--&gt;[ Super Tux Kart (OpenGL)], [http://www.dusabledanslherbe.eu/AROSPage/F1Spirit.30.html F1 Spirit (OpenGL)], [http://bszili.morphos.me/index.html MultiRacer], [https://bszili.morphos.me/ Speed Dreams], [https://archives.arosworld.org/?function=showfile&amp;file=game/driving/dethrace-0.10.1.x86_64-aros-v11.zip Carmageddon dethrace 64bit], [], 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://bszili.morphos.me/index.html Speed Dreams], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12], [http://bszili.morphos.me/index.html TORCS], 
|-
|&lt;!--Sub Menu--&gt;Games 1st first person DRPG [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/OpenEnroth/OpenEnroth OpenEnroth MM], []
|&lt;!--AROS--&gt;[https://github.com/BSzili/aros-stuff Arx Libertatis], [http://www.playfuljs.com/a-first-person-engine-in-265-lines/ js raycaster], [https://github.com/Dorthu/es6-crpg webgl], [https://github.com/sonountaleban/AmiShockolate System Shock], [], [], 
|&lt;!--AmigaOS--&gt;Phantasie, Faery Tale, Dungeon Master, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 3rd third person action CRPG  [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/alexbatalov/fallout1-ce fallout ce], [https://github.com/rwengine/openrw gta3], [https://github.com/gta-reversed/gta-reversed gta3 sa], [https://github.com/mrxenginner/reVC gta3 vc revc], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ fheroes2 homm2], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ breakhack], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ devilutionx diablo 1 hellfire], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ fallout 1], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ stratagus], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ hostile-takeover], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games isometric RPG [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/topics/dungeon?l=javascript Dungeon], [], [https://github.com/clintbellanger/heroine-dusk JS Dusk], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying nethack], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying GemRB], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games card based RPG [https://github.com/open-duelyst/duelyst Duelyst], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games turn based tactics RPG [], [], [], [], [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy UFO AI], [http://play.freeciv.org/ FreeCiv], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Strategy [http://rtsgus.org/ RTSgus], [http://stargus.sourceforge.net/ Stargus], [https://github.com/KD-lab-Open-Source/Perimeter Perimeter], [https://matty77.itch.io/conflict-3049 conflict-3049], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy MegaGlest (OpenGL)], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ signus], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=140&amp;pid=12446#post_12446 Wargus warcraft 2 setup], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Rhythm, Beat, Step [], [], [https://clonehero.net/ clonehero], [https://github.com/MatteoGodzilla/Dj-Engine Dj-Engine], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc Frets on Fire], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Shoot Em Ups [http://www.mhgames.org/oldies/formido/ Formido], [http://code.google.com/p/violetland/ Violetland], 
||&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Open Tyrian], [http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ Alien Blaster], [https://github.com/OpenFodder/openfodder OpenFodder], [https://archives.arosworld.org/?function=showfile&amp;file=game/action/ tbftss The Battle for the Solar System: the Pandora War]
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ The Battle for the Solar System: the Pandora War]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Simulations [http://scp.indiegames.us/ Freespace 2], [http://www.heptargon.de/gl-117/gl-117.html GL117], [http://code.google.com/p/corsix-th/ Theme Hospital], [http://code.google.com/p/freerct/ Rollercoaster Tycoon], [http://hedgewars.org/ Hedgewars], [https://github.com/raceintospace/raceintospace raceintospace], [https://github.com/Return-To-The-Roots RTTR Settlers 2], [https://github.com/OoliteProject/oolite oolite elite], [https://github.com/fesh0r/newkind newkind elite], [https://github.com/bohemiainteractive/cwr Arma Cold War Src], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;SimCity, SimAnt, Sim Hospital, Theme Park, [https://github.com/angree/openttd_amiga_68k openttd amiga_68k], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Life Sim [https://github.com/ACreTeam/forest Animal Crossing], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Horror [https://github.com/Mikompilation/MikuPan Fatal Frame], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Sandbox Voxel Open World Exploration [https://github.com/ClassiCube/ Classicube],[http://www.michaelfogleman.com/craft/ Craft], [https://github.com/tothpaul/DelphiCraft DelphiCraft],[https://www.minetest.net/ Luanti formerly Minetest], [ infiniminer], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Battle Royale [https://bruh.io/ Play.Bruh.io], [https://www.coolmathgames.com/0-copter Copter Royale], [https://surviv.io/ Surviv.io], [https://nuggetroyale.io/#Ketchup Nugget Royale], [https://miniroyale2.io/ Miniroyale2.io], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Tower Defense [https://chriscourses.github.io/tower-defense/ HTML5], [https://github.com/SBardak/Tower-Defense-Game TD C++], [https://github.com/bdoms/love_defense LUA and LOVE], [https://github.com/HyOsori/Osori-WebGame HTML5], [https://github.com/PascalCorpsman/ConfigTD ConfigTD Pascal], [https://github.com/GloriousEggroll/wine-ge-custom Wine], []
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12871#post_12871 Plants vs Zombies PvZ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Visual Novel Engines [https://github.com/diane1f0cd/VisualNovelTemplate Visual Novel Template], [https://github.com/Kirilllive/tuesday-js Tuesday JS], [https://github.com/tejasnayak25/vnsutra vnsutra], [https://github.com/weetabix-su/renpsp-dev RenPSP], [https://github.com/Galladite27/ONScripter-EN ONScripter-EN], [https://github.com/NathanGuilhot/VNES-Raylib https://github.com/NathanGuilhot/VNES VNES in Raylib], [https://www.renpy.org/latest.html renpy ren'py python based], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Reality VR [https://gitlab.com/madsbuvi/openmw openmw vr], [https://github.com/Team-Beef-Studios/BeefRaiderXR BeefRaiderXR], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Table Top VTT [ Roll20], [https://www.owlbear.rodeo/ owlbear rodeo], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Computer assisted TableTop TTRPG OSR [https://www.rpgsolo.com/play.php RPGSolo], [https://github.com/fpsvogel/solo-ttrpgs Solo TTRPG], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 2D 3D Engines [https://github.com/fegennari/3DWorld 3DWorld], [https://github.com/GarageGames/Torque3D Torque3D], [https://github.com/gameplay3d/GamePlay GamePlay 3D],  [https://www.babylonjs.com/ BabylonJS ], [ Godot], [ Ogre], [ Crystal Space], [https://github.com/JacobHess03/ Dragon-Quest like], [https://github.com/bjornbytes/lovr Lua LOVE for 2D LOVR for 3D], [], 
|&lt;!--AROS--&gt;[https://www.arkhamdev.net/wiki.htm?id=agx Arkham Development antiryadgx 8.9 lts with register], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/alpyre/Sevgi_Engine Sevgi Engine], [], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games C based game frameworks [https://github.com/orangeduck/Corange Corange], [https://github.com/scottcgi/Mojoc Mojoc], [https://orx-project.org/ Orx], [https://github.com/ioquake/ioq3 Quake 3], [https://www.mapeditor.org/ Tiled], [https://www.raylib.com/ 2d Raylib], [https://github.com/Rabios/awesome-raylib other raylib], [https://github.com/MrFrenik/gunslinger Gunslinger], [https://o3de.org/ o3d], [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/library GLFW], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/library Raylib 5], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games RPGMaker MV/MZ-compatible projects [https://github.com/Psychronic-Games/RPGReactor RPGReactor js],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Pinball [https://github.com/vpinball/vpinball vpinball], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games unpack unarc [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}


==Application Guides==

[[#top|...to the top]]

===Web Browser===

OWB is now at version 2.0 (which got an engine refresh, from July 2015 to February 2019) and 3.0.

This latest version has a good support for many/most web sites, even YouTube web page now works. [https://www.bilibili.tv/en/search untested] 

This improved compatibility comes at the expense of higher RAM usage (now 1GB RAM is the absolute minimum). 

Also, keep in mind that the lack of a JIT (Just-In-Time) JS compiler on the 32 bit version, makes the web surfing a bit slow. 

Only the 64 bit version of OWB 2.0 will have JIT enabled, thus benefitting of more speed. There are tooltypes that can be added to the icon to provide further features JIT, MSE etc 


Certificates from [https://curl.se/docs/caextract.html ca certs], 


DNS tracking blocking with [https://easylist.to/easylist/easylist.txt easylist.txt] in PROGDIR:Conf before starting browser with enabled AdBlock [https://github.com/easylist/easylist/tree/master easylist], [https://gitlab.com/eyeo anti abp], [https://firebog.net/ big blocklist], [https://github.com/StevenBlack/hosts Steves], [], [], 

This can be enabled with OWB Odyssey with Windows -&gt; Content Blocking and Windows -&gt; Messages and enter 

 https://www.youtube.com/api/stats/ads*
 https://www.youtube.com/pagead/adview*
 https://www.youtube.com#@##player-ads*

into your custom filters 


Element blocker browser extension might be needed for [https://github.com/easylist/easylist/wiki/Youtube-Issues youtube], [ mid roll], [ pre roll], [ ],  


OWB speed is much better when running from RAM Disk, the best way is to add the below into your S:User-Startup which copies OWB drawer from Extras:Internet/OWB to RAM Disk: 

So add this :
&lt;pre&gt;
copy Extras:Internet/OWB Ram:OWB/ ALL CLONE &gt;NIL:
copy Extras:Internet/OWB.info Ram: &gt;NIL:
&lt;/pre&gt;
Open RAM Disk and open OWB drawer and double click on OWB icon so that the above icon tooltypes are activated 

Problems are that the copy time is long (around 20 seconds added in the background), but we can make it faster if we delete useless files from the OWB drawer (docs, …)
If you don’t copy the drawer back onto the HD, you won’t save your cache, cookies, passwords… So you need a script for it.


Error messages 

SSL error &quot;cant verify with ca-certificates&quot;, check bios clock time date is correct 

Error 6, try checking networking prefs settings and Save / Use preferences again or a '''few times''' otherwise the network chipset may not be compatible with Aros 


[https://www.google.com/search?q=%s&amp;udm=14 Google search without AI overview] 


===E-mail===

 YAM does not support SSL and most mail providers now switched to encrypted SMTP/POP3 connections


====SimpleMail====

SimpleMail supports IMAP and appears to work with GMail, but it's never been reliable enough, it can crash with large mailboxes.

Please read more on this [http://www.freelists.org/list/simplemail-usr User list]


 GMail

Be sure to activate the pop3 usage in your gmail account setup / configuration first.

pop3: 
pop.gmail.com
Use SSL: Yes
Port: 995

smtp:
smtp.gmail.com (with authentication)
Use Authentication: Yes
Use SSL: Yes
Port: 465 or 587


 Hotmail/MSN/outlook/Microsoft Mail mid-2017, all outlook.com accounts will be migrated to Office 365 / Exchange

Most users are currently on POP which does not allow showing folders and many other features (technical limitations of POP3). With Microsoft IMAP you will get folders, sync read/unread, and show flags. You still won't get push though, as Microsoft has not turned on the IMAP Idle command as at Sept 2013.

If you want to try it, you need to first remove (you can't edit) your pop account (long-press the account on the accounts screen, delete account). Then set it up this way:

1. Email/Password
2. Manual
3. IMAP
4.

* Incoming: imap-mail.outlook.com, port 993, SSL/TLS should be checked
* Outgoing: smtp-mail.outlook.com, port 587, SSL/TLS should be checked
* POP server name pop-mail.outlook.com, port 995, POP encryption method SSL

 Yahoo  Mail

On April 24, 2002 Yahoo ceased to offer POP access to its free mail service. Introducing instead a yearly payment feature, allowing users POP3 and IMAP server support, along with such benefits as larger file attachment sizes and no adverts.

Sorry to see Yahoo leaving its users to cough up for the privilege of accessing their mail. Understandable, when competing against rivals such as Gmail and Hotmail who hold a large majority of users and were hacked in 2014 as well.


Incoming Mail (IMAP) Server

* Server - imap.mail.yahoo.com
* Port - 993
* Requires SSL - Yes

Outgoing Mail (SMTP) Server

* Server - smtp.mail.yahoo.com
* Port - 465 or 587
* Requires SSL - Yes
* Requires authentication - Yes

Your login info

* Email address - Your full email address (name@domain.com)
* Password - Your account's password
* Requires authentication - Yes


Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a subscription subs fee to have access to SMTP and POP3

* Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
* “Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
* “Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
* “Password” – Your Yahoo Mail password.

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

* Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.


====YAM Yet Another Mailer====

 YAM does not support SSL and most mail providers have now switched to encrypted SMTP/POP3 connections

This email client is POP3 only if the SSL library is available [http://www.freelists.org/list/yam YAM Freelists]

One of the downsides of using a POP3 mailer unfortunately - you have to set an option not to delete the mail if you want it left on the server. IMAP keeps all the emails on the server.

Possible issues

Sending mail issues is probably a matter of using your ISP's SMTP server, though it could also be an SSL issue.


getting a &quot;Couldn't initialise TLSv1 / SSL error

Use of on-line e-mail accounts with this email client is not possible as it lacks the OpenSSL AmiSSl v3 compatible library

 GMail 
Incoming Mail (POP3) Server - requires SSL: pop.gmail.com
Use SSL: Yes
Port: 995

Outgoing Mail (SMTP) Server - requires TLS: smtp.gmail.com (use authentication)
Use Authentication: Yes
Use STARTTLS: Yes (some clients call this SSL)
Port: 465 or 587

Account Name: your Gmail username (including '@gmail.com')
Email Address: your full Gmail email address (username@gmail.com)
Password: your Gmail password

Anyway, the SMTP is pop.gmail.com port 465 and it uses SSLLv3 Authentication. The POP3 settings are for the same server (pop.gmail.com), only on port 995 instead.


 Outlook.com access

&lt;pre &gt;
Outlook.com SMTP server address: smtp.live.com
Outlook.com SMTP user name: Your full Outlook.com email address (not an alias)
Outlook.com SMTP password: Your Outlook.com password
Outlook.com SMTP port: 587
Outlook.com SMTP TLS/SSL encryption required: yes 
&lt;/pre &gt;


 Yahoo  Mail

&lt;pre &gt;
“POP3 Server” – Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
“SMTP Server” – Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.
“Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
“Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
“Password” – Your Yahoo Mail password.
&lt;/pre &gt;

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a monthly fee to have access to SMTP and POP3


 Microsoft Outlook Express Mail 

1. Get the files to your PC.
By whatever method get the files off your Amiga onto your PC. In the YAM folder you have a number of different folders, one for each of your folders in YAM. Inside that is a file usually some numbers such as 332423.283. YAM created a new file for every single email you received.

2. Open up a brand new Outlook Express. Just configure the account to use 127.0.0.1 as mail servers. It doesn't really matter. You will need to manually create any subfolders you used in YAM.

3. You will need to do a mass rename on all your email files from YAM. Just add a .eml to the end of it. Amazing how PCs still rely mostly on the file name so it knows what sort of file it is rather than just looking at it! There are a number of multiple renamers online to download and free too.

4. Go into each of your folders, inbox, sent items etc. And do a select all then drag the files into Outlook Express (to the relevant folder obviously) Amazingly the file format that YAM used is very compatible with .eml standard and viola your emails appear. With correct dates and working attachments.

5. If you want your email into Microsoft Outlook. Open that up and create a new profile and a new blank PST file. Then go into File Import and choose to import from Outlook Express. And the mail will go into there. And viola.. you have your old email from your Amiga in a more modern day format.


===FTP===

Magellan has a great FTP module. It allows transferring files from/to a FTP server over the Internet or the local network and, even if FTP is perceived as a &quot;thing of the past&quot;, its usability is all inside the client. The FTP thing has a nice side effect too, since every Icaros machine can be a FTP server as well, and our files can be easily transferred from an Icaros machine to another with a little configuration effort.

First of all, we need to know the 'server' IP address. Server is the Icaros machine with the file we are about to download on another Icaros machine, that we're going to call 'client'. To do that, move on the server machine and 1) run Prefs/Services to be sure &quot;FTP file transfer&quot; is enabled (if not, enable it and restart Icaros); 2) run a shell and enter this command:

ifconfig -a

Make a note of the IP address for the network interface used by the local area network. For cabled devices, it usually is net0:. Now go on the client machine and run Magellan:

Perform these actions: 1) click on FTP; 2) click on ADDRESS BOOK; 3) click on &quot;New&quot;. 
You can now add a new entry for your Icaros server machine:

1) Choose a name for your server, in order to spot it immediately in the address book. Enter the IP address you got before.

2) click on Custom Options:


1) go to Miscellaneous in the left menu;

2) Ensure &quot;Passive Transfers&quot; is NOT selected;

3) click on Use. We need to deactivate Passive Transfers because YAFS, the FTP server included in Icaros, only allows active transfers at the current stage. Now, we can finally connect to our new file source:


1) Look into the address book for the newly introduced server, be sure that name and IP address are right, and

2) click on Connect. A new lister with server's &quot;MyWorkspace&quot; contents will appear. You can now transfer files over the network choosing a destination among your local (client's) volumes.

Can be adapted to any FTP client on any platform of your choice, just be sure your client allows Active Transfers as well.


===IRC Internet Relay Chat===

Jabberwocky is ideal for one-to-one social media communication, use IRC if you require one to many. 

Just type a message in ''lowercase''' letters and it will be posted to all in the [ AROS irc channel]. Please do not use UPPER CASE as it is a sign of SHOUTING which is annoying.

Other things to type in - replace &lt;message&gt; with a line of text and &lt;nick&gt; with a person's name

&lt;pre&gt;
/help

/list

/who
/whois &lt;nick&gt;

/msg &lt;nick&gt; &lt;message&gt;

/query &lt;nick&gt; 
&lt;message&gt;s
/query

/away &lt;message&gt;
/away

/quit &lt;going away message&gt; 
&lt;/pre&gt;


[http://irchelp.org/irchelp/new2irc.html#smiley Intro guide here]. IRC Primer can be found here in [http://www.irchelp.org/irchelp/ircprimer.html html], [http://www.irchelp.org/irchelp/text/ircprimer.txt TXT], [http://www.kei.com/irc/IRCprimer1.1.ps PostScript].


Issue the command /me &lt;text&gt; where &lt;text&gt; is the text that should follow your nickname.
Example: /me slaps ajk around a bit with a large trout

/nick &lt;newNick&gt;

/nickserv register &lt;password&gt; &lt;email address&gt;

/ns instead of /nickserv, while others might need /msg nickserv

/nickserv identify &lt;password&gt;

Alternatives:
/ns identify &lt;password&gt;
/msg nickserv identify &lt;password&gt;


==== IRC WookieChat ====

WookieChat is the most complete internet client for communication across the IRC Network. WookieChat allows you to swap ideas and communicate in real-time, you can also exchange Files, Documents, Images and everything else using the application's DCC capabilities.


add smilies drawer/directory

 run wookiechat from the shell and set stack to 1000000 e.g. wookiechat stack 1000000

select a server / server window

* nickname 
* user name 
* real name - optional

Once you configure the client with your preferred screen name, you'll want to find a channel to talk in.


servers

* New Server - click on this to add / add extra - change details in section below this click box 
* New Group
* Delete Entry
* Connect to server
* connect in new tab
* perform on connect

Change details

* Servername - change text in this box to one of the below Server: 
* Port number - no need to change
* Server password
* Channel - add #channel from below 
* auto join - can click this 
* nick registration password,

Click Connect to server button above


&lt;pre&gt;
Server: irc.freenode.net
Channel: #aros
&lt;/pre&gt;

irc://irc.freenode.net/aros

&lt;pre&gt;
Server: chat.amigaworld.net 
Channel: #amigaworld or #amigans 
&lt;/pre&gt;

&lt;pre&gt;
On Sunday evenings USA time usually starting around 3PM EDT (1900 UTC)
Server:irc.superhosts.net
Channel #team*amiga  
&lt;/pre&gt;

&lt;pre&gt;
BitlBee and Minbif are IRCd-like gateways to multiple IM networks
Server: im.bitlbee.org 
Port 6667 
Seems to be most useful on WookieChat as you can be connected to several servers at once. One for Bitlbee and any messages that might come through that. One for your normal IRC chat server. 
&lt;/pre&gt;

[http://www.bitlbee.org/main.php/servers.html Other servers],

&lt;pre&gt;
#Amiga.org - irc.synirc.net eu.synirc.net dissonance.nl.eu.synirc.net (IPv6: 2002:5511:1356:0:216:17ff:fe84:68a) 
twilight.de.eu.synirc.net zero.dk.eu.synirc.net us.synirc.net avarice.az.us.synirc.net envy.il.us.synirc.net harpy.mi.us.synirc.net 
liberty.nj.us.synirc.net snowball.mo.us.synirc.net - Ports 6660-6669 7001 (SSL)
&lt;/pre&gt;

&lt;pre&gt;
Multiple server support
&quot;Perform on connect&quot; scripts and channel auto-joins
Automatic Nickserv login
Tabs for channels and private conversations
CTCP PING, TIME, VERSION, SOUND
Incoming and Outgoing DCC SEND file transfers
Colours for different events
Logging and automatic reloading of logs
mIRC colour code filters
Configurable timestamps
GUI for changing channel modes easily
Configurable highlight keywords
URL Grabber window
Optional outgoing swear word filter
Event sounds for tabs opening, highlighted words, and private messages
DCC CHAT support
Doubleclickable URL's
Support for multiple languages using LOCALE
Clone detection
Auto reconnection to Servers upon disconnection
Command aliases
Chat display can be toggled between AmIRC and mIRC style
Counter for Unread messages
Graphical nicklist and graphical smileys with a popup chooser
&lt;/pre&gt;


====IRC Aircos ====

Double click on Aircos icon in Extras:Networking/Apps/Aircos. It has been set up with a guest account for trial purposes. Though ideally, choose a nickname and password for frequent use of irc. 


====IRC and XMPP Jabberwocky====
 Servers are setup and close down at random 
You sign up to a server that someone else has setup and access chat services through them. 

The two ways to access chat from jabberwocky
&lt;pre &gt;
Jabberwocky -&gt; Server -&gt; XMPP -&gt; open and ad-free 
Jabberwocky -&gt; Server -&gt; Transports (Gateways) -&gt; Proprietary closed systems 
&lt;/pre &gt;

The Jabber.org service connects with all IM services that use XMPP, the open standard for instant messaging and presence over the Internet. The services we connect with include Google Talk (closed), Live Journal Talk, Nimbuzz, Ovi, and thousands more. However, you can not connect from Jabber.org to proprietary services like AIM, ICQ, MSN, Skype, or Yahoo because they don’t yet use XMPP components (XEP-0114) '''but''' you can use Jabber.com's servers and IM gateways (MSN, ICQ, Yahoo etc.) instead.

The best way to use jabberwocky is in conjunction with a public jabber server with '''transports''' to your favorite services, like gtalk, Facebook, yahoo, ICQ, AIM, etc.


You have to register with one of the servers, [https://list.jabber.at/ this list] or [http://www.jabberes.org/servers/ another list], [http://xmpp.net/ this security XMPP list],

Unfortunately jabberwocky can only connect to one server at a time so it is best to check what services each server offers. If you set it up with separate Facebook and google talk accounts, for example, sometimes you'll only get one or the other.

Jabberwocky open a window where the Jabber server part is typed in as well as your Nickname and Password.

Jabber ID (JID) identifies you to the server and other users.

Once registered the next step is to goto Jabberwocky's &quot;Windows&quot; menu and select the &quot;Agents&quot; option. The &quot;Agents List&quot; window will open.

Roster (contacts list)

[http://search.wensley.org.uk/ Chatrooms] (MUC) are available

File Transfer - can send and receive files through the Jabber service but not with other services like IRC, ICQ, AIM or Yahoo. All you need is an installed webbrowser and OpenURL.

Clickable URLs - The message window uses Mailtext.mcc and you can set a URL action in the MUI mailtext prefs like SYS:Utils/OpenURL %s NEWWIN.

There is no consistent Skype like (H.323 VoIP) video conferencing available over Jabber. The move from xmpp to Jingle should help but no support on any amiga-like systems at the moment. [http://aminet.net/package/dev/src/AmiPhoneSrc192 AmiPhone] and [http://www.lysator.liu.se/%28frame,faq,nobg,useframes%29/ahi/v4-site/ Speak Freely] was an early attempt voice only contact. SIP and Asterisk are other PBX options.


 Facebook

If you're using the XMPP transport provided by Facebook themselves, chat.facebook.com, it looks like they're now requiring SSL transport. This means jabberwocky method below will no longer work. The best thing to do is to create an ID on a public jabber server which has a Facebook gateway.

&lt;pre &gt;
1. launch jabberwocky
2. if the login window doesn't appear on launch, select 'account' from the jabberwocky menu
3. your jabber ID will be user@chat.facebook.com where user is your user ID
4. your password is your normal facebook password
5. to save this for next time, click the popup gadget next to the ID field

6. click the 'add' button
7. click the 'close' button
8. click the 'connect' button
&lt;/pre &gt;

you're done. you can also click the 'save as default account' button if you want. jabberwocky configured to auto-connect when launching the program, but you can configure as you like. there is amigaguide documentation included with jabberwocky.

[http://amigaworld.net/modules/newbb/viewtopic.php?topic_id=37085&amp;forum=32 Read more here]

for Facebook users, you can log-in directly to Facebook with jabberwocky. just sign in as @chat.facebook.com with your Facebook password as the password


 Twitter

For a few years, there has been added a twitter transport. Servers include [http://jabber.hot-chilli.net/ jabber.hot-chili.net],  and .

An [http://jabber.hot-chilli.net/tag/how-tos/ How-to]

:Read [http://jabber.hot-chilli.net/2010/05/09/twitter-transport-working/ more]

 Instagram 

no support at the moment best to use a web browser based client

 ICQ

The new version (beta) of StriCQ uses a newer ICQ protocol. Most of the ICQ Jabber Transports still use an older ICQ protocol. You can only talk one-way to StriCQ using the older Transports. Only the newer ICQv7 Transport lets you talk both ways to StriCQ. Look at the server lists in the first section to check.

Register on a Jabber server, e.g. this one works: http://www.jabber.de/
Then login into Jabberwocky with the following login data e.g. xxx@jabber.de / Password: xxx Now add your ICQ account under the window-&gt;Agents-&gt;&quot;Register&quot;. Now Jabberwocky connects via the Jabber.de server with your ICQ account.

 Yahoo Messenger

although yahoo! does not use xmpp protocol, you should be able to use the transport methods to gain access and post your replies

 MSN

early months of 2013 Microsoft will ditch MSN Messenger client and force everyone to use Skype...but MSN protocol and servers will keep working as usual for quite a long time....

Occasionally the Messenger servers have been experiencing problems signing in.  You may need to sign in at www.outlook.com and then try again.  It may also take multiple tries to sign in.  (This also affects you if you’re using Skype.)

You have to check each servers' Agents List to see what transports (MSN protocol, ICQ protocol, etc.) are supported or use the list address' provided in the section above. Then register with each transport (IRC, MSN, ICQ, etc.) to which you need access. After registering you can Connect to start chatting.

msn.jabber.com/registered should appear in the window.

From this [http://tech.dir.groups.yahoo.com/group/amiga-jabberwocky/message/1378 JW group] guide which  helps with this process in a clear, step by step procedure.

1. Sign up on MSN's site for a passport account. This typically involves getting a Hotmail address.

2. Log on to the Jabber server of your choice and do the following:

* Select the &quot;Windows/Agents&quot; menu option in Jabberwocky.
* Select the MSN Agent from the list presented by the server.
* Click the Register button to open a new window asking for:
**Username = passort account email address, typically your hotmail address.
**Nick = Screen name to be shown to anyone you add to your buddy list.
**Password = Password for your passport account/hotmail address.
* Click the Register button at the bottom of the new window.

3. If all goes well, you will see the MSN Gateway added to your buddy list. If not, repeat part 2 on another server. Some servers may show MSN in their list of available agents, but have not updated their software for the latest protocols used by MSN.

4. Once you are registered, you can now add people to your buddy list. Note that you need to include the '''msn.''' ahead of the servername so that it knows what gateway agent to use. Some servers may use a slight variation and require '''msg.gate.''' before the server name, so try both to see what works.

If my friend's msn was amiga@hotmail.co.uk and my jabber server was @jabber.meta.net.nz..
then amiga'''%'''hotmail.com@'''msn.'''jabber.meta.net.nz

or another the trick to import MSN contacts is that you don't type the hotmail URL but the passport URL... e.g. Instead of: goodvibe%hotmail.com@msn.jabber.com  You type: goodvibe%passport.com@msn.jabber.com 
And the thing about importing contacts I'm afraid you'll have to do it by hand, one at the time...

 Google Talk

any XMPP server will work, but you have to add your contacts manually. a google talk user is typically either @gmail.com or @talk.google.com. a true gtalk transport is nice because it brings your contacts to you and (can) also support file transfers to/from google talk users.

implement Jingle a set of extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP)

support ended early 2014 as Google moved to Google+ Hangouts which uses it own proprietary format


===Video Player MPlayer===

Many of the menu features (such as doubling) do not work with the current version of mplayer but using

4:3
 mplayer -vf scale=800:600 file.avi

16:9
 mplayer -vf scale=854:480 file.avi

if you want gui use;
 mplayer -gui 1 &lt;other params&gt; file.avi

&lt;pre &gt;
stack 1000000

; using AspireOS 1.xx 
; copy FROM SYS:Extras/Multimedia/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 1.x 
; copy FROM SYS:Tools/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 2.x 
; copy FROM SYS:Utilities/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

cd RAM:MPlayer
run MPlayer -gui &gt; Nil:
;run MPlayer -gui -ao ahi_dev -playlist http://www.radio-paralax.de/listen.pls &gt; Nil: 
&lt;/pre &gt;

$ mplayer rtsp://127.0.0.1:554/sample_300kbit.mp4


MPlayer supports multicast streaming, and rtp/rtsp protocols (it might require [http://www.live555.com/openRTSP/ live555 library] to work with some streams). But you might have to build it where it's disabled. Also, multicast won't work with some AmiTCP-likes. MIAMI supported it, though.

AROS supports IPv4 (old but works) and this includes the needed address space for RTP.

If you mean multicast via RTP - mplayer handles it. You can even force UDP over TCP

-rtsp-stream-over-tcp

If the rtsp Real Time Streaming Protocol  server needs authentification:

-user -passwd


MPlayer - Menu - Open Playlist and load already downloaded .pls or .m3u file - auto starts around 4 percent cache

MPlayer - Menu - Open Stream and copy one of the .pls lines below into space allowed, press OK and press play button on main gui interface


Old 8bit 16bit remixes chip tune game music 
 
http://www.radio-paralax.de/listen.pls 

http://scenesat.com/

http://www.shoutcast.com/radio/Amiga

http://www.theoldcomputer.com/retro_radio/RetroRadio_Main.htm

http://www.kohina.com/

http://www.remix64.com/

http://retrogamer.net/forum/

http://retroasylum.podomatic.com/rss2.xml

http://retrogamesquad.com/

http://www.retronauts.com/

http://monsterfeet.com/noquarter/

http://www.retrogamingradio.com/

http://www.radiofeeds.co.uk/mp3.asp


[[#top|...to the top]]

====ZunePaint==== 

simplified typical workflow

* importing and organizing and photo management
* making global and regional local correction(s) - recalculation is necessary after each adjustment as it is not in real-time 
* exporting your images in the best format available with the preservation of metadata


Whilst achieving 80% of a great photo with just a filter, the remaining 20% comes from a manual fine-tuning of specific image attributes.


For photojournalism, documentary, and event coverage, minimal touching is recommended. Stick to Camera Raw for such shots, and limit changes to level adjustment, sharpness, noise reduction, and white balance correction.

For fashion or portrait shoots, a large amount of adjustment is allowed and usually ends up far from the original. Skin smoothing, blemish removal, eye touch-ups, etc. are common.  Might alter the background a bit to emphasize the subject.

Product photography usually requires a lot of sharpening, spot removal, and focus stacking.

For landscape shots, best results are achieved by doing the maximum amount of preparation before/while taking the shot. No amount of processing can match timing, proper lighting, correct gear, optimal settings, etc. Excessive post-processing might give you a dramatic shot but best avoided in the long term.


* White Balance - Left Amiga or F12 and K and under &quot;Misc color effects&quot; tab with a pull down for White Balance - color temperature also known as AKA tint (movies) or tones (painting) - warm temp raise red reduce green blue - cool raise blue lower red green 
* Exposure - exposure compensation, highlight/shadow recovery
* Noise Reduction - during RAW development or using external software
* Lens Corrections - distortion, vignetting, chromatic aberrations
* Detail - capture sharpening and local contrast enhancement
* Contrast - black point, levels (sliders) and curves tools (F12 and K) 
* Framing - straighten () and crop (F12 and F) 
* Refinements - color adjustments and selective enhancements - Left Amiga or F12 and K for RGB and YUV histogram tabs - 
* Resizing - enlarge for a print or downsize for the web or email (F12 and D) 
* Output Sharpening - customized for your subject matter and print/screen size


White Balance - F12 and K

scan your image for a shade which was meant to be white (neutral with each RGB value being equal) like paper or plastic which is in the same light as the subject of the picture. Use the dropper tool to select this color, similar colours will shift and you will have selected the perfect white balance for your part of the image - for the whole picture make sure RAZ or CLR button at the bottom is pressed before applying to the image above.


Exposure correction

F12 and K - YUV Y luminosity - RGB extra red tint - move red curve slightly down and move blue green curves slightly up

Workflows in practice

* Undo - Right AROS key or F12 and Z 
* Redo - Right AROS key or F12 and R

First flatten your image (if necessary) and then do a rotation until the picture looks level. 
* Crop the picture. Click the selection button and drag a box over the area of the picture you want to keep. Press the crop button and the rest of the photo will be gone. 
* Adjust your saturation, exposure, hue levels, etc., (right AROS Key and K for color correction) until you are happy with the photo. Make sure you zoom in all of the way to 100% and look the photo over, zoom back out and move around. Look for obvious problems with the picture. 
* After coloring and exposure do a sharpen (Right AROS key and E for Convolution and select drop down option needed), e.g. set the matrix to 5x5 (roughly equivalent Amount to 60%) and set the Radius to 1.0. Click OK.


And save your picture


Implemented or would like to see for simplification and ease of use

basic filters (presets) like black and white, monochrome, edge detection (sobel), motion/gaussian blur, 
* negative, sepiatone, retro vintage, night vision, colour tint, color gradient, color temperature, glows, fire, lightning, lens flare, emboss, filmic, pixelate mezzotint, antialias, etc.

adjust / cosmetic tools such as crop, 
* reshaping tools, straighten, smear, smooth, perspective, liquify, bloat, pucker, push pixels in any direction, dispersion, transform like warp, blending with soft light, page-curl, whirl, ripple, fisheye, neon,  etc. 
* red eye fixing, blemish remover, skin smoothing, teeth whitener, make eyes look brighter, desaturate,

effects like oil paint, cartoon, pencil sketch, charcoal, noise/matrix like sharpen/unsharpen, (right AROS key with A for Artistic effects) 
* blend two image, gradient blend, masking blend, explode, implode, custom collage, surreal painting, comic book style, needlepoint, stained glass, watercolor, mosaic, stencil/outline, crayon, chalk, etc.

borders such as 
* dropshadow, rounded, blurred, color tint, picture frame, film strip polaroid, bevelled edge, etc.

brushes e.g.
* frost, smoke, etc.

and manual control of

fix lens issues including vignetting (darkening), color fringing and barrel distortion, and chromatic and geometric aberration -  lens and body profiles

perspective correction

levels - directly modify the levels of the tone-values of an image, by using sliders for highlights, midtones and shadows

curves -  Color Adjustment and Brightness/Contrast

color balance

one single color transparent (alpha channel (color information/selections) for masking and/or blending ) for backgrounds, etc.

Threshold indicates how much other colors will be considered mixture of the removed color and non-removed colors

decompose layer into a set of layers with each holding a different type of pattern that is visible within the image

any selection using any selecting tools like lasso tool, marquee tool etc. the selection will temporarily be save to alpha 
If you create your image without transparency then the Alpha channel is not present, but you can add later.

File formats like .psd (Photoshop file has layers, masks etc.  contains edited sensor data. The original sensor data is no longer available) .xcf .raw .hdr

Image Picture Formats
* low dynamic range (JPEG, PNG, TIFF 8-bit), 16-bit (PPM, TIFF), typically as a 16-bit TIFF in either ProPhoto or AdobeRGB colorspace -  TIFF files are also fairly universal – although, if they contain proprietary data, such as Photoshop Adjustment Layers or Smart Filters, then they can only be opened by Photoshop making them proprietary.
* linear high dynamic range (HDR) images (PFM, [http://www.openexr.com/ ILM .EXR], jpg, [http://aminet.net/util/dtype cr2] (canon tiff based), hdr, NEF, CRW, ARW, MRW, ORF, RAF (Fuji), PEF, DCR, SRF, ERF, DNG files are RAW converted to an Adobe proprietary format - a container that can embed the raw file as well as the information needed to open it) 
An old version of [http://archives.aros-exec.org/index.php?function=browse&amp;cat=graphics/convert dcraw]

There is no single RAW file format. Each camera manufacturer has one or more unique RAW formats. RAW files contain the brightness levels data captured by the camera sensor. This data cannot be modified. A second smaller file, separate XML file, or within a database with instructions for the RAW processor to change exposure, saturation etc. The extra data can be changed but the original sensor data is still there. RAW is technically least compatible.

A raw file is high-bit (usually 12 or 14 bits of information) but a camera-generated TIFF file will be usually converted by the camera (compressed, downsampled) to 8 bits. The raw file has no embedded color balance or color space, but the TIFF has both. These three things (smaller bit depth, embedded color balance, and embedded color space) make it so that the TIFF will lose quality more quickly with image adjustments than the raw file. The camera-generated TIFF image is much more like a camera processed JPEG than a raw file. A strong advantage goes to the raw file. The power of RAW files, such as the ability to set any color temperature non-destructively and will contain more tonal values.

The principle of preserving the maximum amount of information to as late as possible in the process. The final conversion - which will always effectively represent a &quot;downsampling&quot; - should prevent as much loss as possible.

Once you save it as TIFF, you throw away some of that data irretrievably. When saving in the lossy JPEG format, you get tremendous file size savings, but you've irreversibly thrown away a lot of image data. As long as you have the RAW file, original or otherwise, you have access to all of the image data as captured.

Keyboard equivalence with Photoshop(tm) would help 

File
PHOTOSHOP	SHORTCUT	GIMP
New	Ctrl+n	New
Open	Ctrl+o	Open
Close	Ctrl+w	Close
Save	Ctrl+s	Save
Save as	Shift+Ctrl+s	Save as
Revert	F12	Revert
Print	Ctrl+p	Print
Exit	Ctrl+q	Quit
 
Edit
PHOTOSHOP	SHORTCUT	GIMP
Undo/Redo (1 level)	Ctrl+z	Undo (Redo is Shift+Ctrl+z)
Cut	Ctrl+x	Cut
Copy	Ctrl+c	Copy
Paste	Ctrl+v	Paste
Paste Into	Shift+Ctrl+v	Paste Into
Fill with FG color	Alt+Backspace	Fill with FG color
Fill with BG color	Control+Backspace	Fill with BG color
 
Image/Colors
PHOTOSHOP	SHORTCUT	GIMP
Levels	Ctrl+l	Levels
Auto Contrast	Shift+Ctrl+Alt+l	Stretch Contrast (same?)
Curves	Ctrl+m	Curves
Color Balance	Ctrl+b	Color Balance
Hue/Saturation	Ctrl+u	Hue-Saturation
Desaturate	Shift+Ctrl+u	Desaturate
Invert	Ctrl+i	Invert
Default Colors	d	Default Colors
Switch Colors	x	Switch Colors
 
Layer
PHOTOSHOP	SHORTCUT	GIMP
New Layer	Shift+Ctrl+n	New Layer
Layer via Copy	Ctrl+j	Duplicate Layer
Bring (layer) to Front	Shift+Ctrl+]	Layer to Top
Send (layer) to Back	Shift+Ctrl+[	Layer to Bottom
Bring (layer) Forward	Ctrl+]	Raise Layer
Send (layer) Backward	Ctrl+[	Lower Layer
Select Top Layer	Shift+Alt+]	Select Top Layer
Select Bottom Layer	Shift+Alt+[	Select Bottom Layer
Select One Layer Forward	Alt+]	Select Previous Layer
Select One Layer Backward	Alt+[	Select Next Layer
Merge Down	Ctrl+e	Merge Down
Merge Visible	Shift+Ctrl+e	Merge Visible
Preserve Transparency	/	Keep Transparency
Cycle Modes Forwards	Shift+=	Next Layer Mode
Cycle Modes Backwards	Shift+-	Previous Layer Mode
 
Select
PHOTOSHOP	SHORTCUT	GIMP
Select All	Ctrl+a	Select All
Deselect	Ctrl+d	Select None
Inverse	Shift+Ctrl+i	Invert
Feather	Ctrl+Alt+d	Feather
 
View
PHOTOSHOP	SHORTCUT	GIMP
Zoom In	Ctrl+=	Zoom In
Zoom Out	Ctrl+-	Zoom Out
Fit on Screen	Ctrl+0	Zoom to Fit Window
Actual Pixels	Ctrl+Alt+0	Zoom 1:1
Show/Hide Extras	Ctrl+h	Toggle Show Selection (close enough?)
Show/Hide Guides	Ctrl+'	Toggle Show Guides
Show/Hide Grid	Ctrl+Alt+'	Toggle Show Grid
Show/Hide Rulers	Ctrl+r	Toggle Show Rulers
Snap	Ctrl+;	Snap to Guides
Scroll View Up	Page Up	Scroll Page Up
Scroll View Down	Page Down	Scroll Page Down
Scroll View Left	Ctrl+Page Up	Scroll Page Left
Scroll View Right	Ctrl+Page Down	Scroll Page Right
 
Window/Dialogs
PHOTOSHOP	SHORTCUT	GIMP
?	F5	Tools Dialog
Color Tab	F6	Colors Dialog
Layers Tab	F7	Layers Dialog
Info Tab	F8	Image Information
 
Tools
PHOTOSHOP	SHORTCUT	GIMP
Rectangular Marquee Tool	m	Rect Select Tool
Elliptical Marquee Tool	Shift+m	Ellipse Select Tool
 	*This is a toggle between 'Elliptical Marquee Tool' and 'Rectangular Marquee Tool' in Photoshop	 
Move Tool	v	Move Tool
Lasso Tool	l	Free Select Tool
Magic Wand Tool	w	Fuzzy Select Tool
Crop Tool	c	Crop &amp; Resize Tool
Airbrush Tool	j	Airbrush Tool
Paintbrush Tool	b	Paintbrush Tool
Clone Stamp Tool	s	Clone Stamp Tool
Eraser Tool	e	Eraser Tool
Gradient Tool	g	Blend Tool
Paint Bucket Tool	Shift+g	Bucket Fill Tool
 	*This is a toggle between 'Paint Bucket Tool' and 'Gradient Tool' in Photoshop	 
Blur Tool	r	Convolve Tool
Dodge Tool	o	DodgeBurn Tool
Type Tool	t	Text Tool
Pen Tool	p	Bezier Select Tool
Eye Dropper Tool	i	Color Picker Tool
Zoom Tool	z	Magnify Tool
Previous Brush	,	Previous Brush
Next Brush	.	Next Brush
First Brush	Shift+&lt;	First Brush
Last Brush	Shift+&gt;	Last Brush
Decrease Brush Size	[	Decrease Brush Size
Increase Brush Size	]	Increase Brush Size
Decrease Brush Hardness	{	Decrease Brush Hardness
Increase Brush Hardness	}	Increase Brush Hardness
 
Help
PHOTOSHOP	SHORTCUT	GIMP
Help	F1	Help
Context Help	Shift+F1	Context Help
 
Misc.
PHOTOSHOP	SHORTCUT	GIMP
Last Filter	Ctrl+f	Repeat Last Filter
?	Shift+Ctrl+f	Reshow Last Filter
Preferences	Ctrl+k	Preferences
Liquify	Shift+Ctrl+x	IWarp (close enough?)
Toggle Quick Mask	q	Toggle Quick Mask


Spotlights - triangle of white opaque shape

Cutting out and/or replacing unwanted background or features - select large areas with the selection option like the Magic Wand tool (aka Color Range) or the Lasso (quick and fast) with feather 2 to soften edge or the pen tool which adds points/lines/Bézier curves (better control but slower), hold down the shift button as you click to add extra points/areas of the subject matter to remove. Increase the tolerance to cover more areas. To subtract from your selection hold down alt as you're clicking. 
* Layer masks are a better way of working than Erase they clip (black hides/hidden white visible/reveal). Clone Stamp can be simulated by   and brushes for other areas. 
* Leave the fine details like hair, fur, etc. to later with lasso and the shift key to draw a line all the way around your subject. Gradient Mapping - Inverse - Mask. i.e. Refine your selected image with edge detection and using the radius and edge options / adjuster (increase/decrease contrast) so that you will capture more fine detail from the background allowing easier removal. 
Remove fringe/halo

saving image as png rather than jpg/jpeg to keep transparency background intact.


Implemented [http://colorizer.org/ colour model representations] [http://paulbourke.net/texture_colour/colourspace/ Mathematical approach] - Photo stills are spatially 2d (h and w), but are colorimetrically 3d (r g and b, or H L S, or Y U V etc.) as well. 
* RGB - split cubed mapped color model for photos and computer graphics hardware using the light spectrum (adding and subtracting) 
* YUV - Y-Lightness U-blue/yellow V-red/cyan (similar to YPbPr and YCbCr) used in the PAL, NTSC, and SECAM composite digital TV color [http://crewofone.com/2012/chroma-subsampling-and-transcoding/#comment-7299 video]


Histograms

White balanced (neutral) if the spike happens in the same place in each channel of the RGB graphs. If not, you're not balanced. 
If you have sky you'll see the blue channel further off to the right.

RGB is best one to change colours. These elements RGB is a 3-channel format containing data for Red, Green, and Blue in your photo scale between 0 and 255. The area in a picture that appears to be brighter/whiter contains more red color as compared to the area which is relatively darker. Similarly in the green channel the area that appears to be darker contains less amount of green color as compared to the area that appears to be brighter.  Similarly in the blue channel the area appears to be darker contains less amount of blue color as compared to the area that appears to be brighter. Brightness luminance histogram also matches the green histogram more than any other color - human eye interprets green better e.g. RGB rough ratio 15/55/30%

RGBA (RGB+A, A means alpha channel) .  The alpha channel is used for &quot;alpha compositing&quot;, which can mostly be associated as &quot;opacity&quot;.  AROS deals in RGB with two digits for every color (red, green, blue), in ARGB you have two additional hex digits for the alpha channel.

The shadows are represented by the left third of the graph.  The highlights are represented by the right third.  And the midtones are, of course, in the middle.  The higher the black peaks in the graph, the more pixels are concentrated in that tonal range (total black area). 
By moving the black endpoint, which identifies the shadows (darkness) and a white light endpoint (brightness) up and down either sides of the graph, colors are adjusted based on these points. 
By dragging the central one, can increased the midtones and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .


RGB Curves

* Move left endpoint (black point) up or right endpoint (white point) up brightens 
* Move left endpoint down or right endpoint down darkens

Color Curves

* Dragging up on the Red Curve increases the intensity of the reds in the image but 
* Dragging down on the Red Curve decreases the intensity of the reds and thus increases the apparent intensity of its complimentary color, cyan. Green’s complimentary color is magenta, and blue’s is yellow.
&lt;pre&gt;
 Red &lt;-&gt; Cyan
 Green &lt;-&gt;Magenta
 Blue &lt;-&gt;Yellow 
&lt;/pre&gt;

YUV Best option to analyse and pull out statistical elements of any picture (i.e.  separate luminance data from color data). The line in Y luma tone box represents the brightness of the image with the point in the bottom left been black, and the point in the top right as white.  A low-contrast image has a concentrated clump of values nearer to the center of the graph. By comparison, a high-contrast image has a wider distribution of values across the entire width of the Histogram.   A histogram that is skewed to the right would indicate a picture that is a bit overexposed because most of the color data is on the lighter side (increase exposure with higher value F), while a histogram with the curve on the left shows a picture that is underexposed. This is good information to have when using post-processing software because it shows you not only where the color data exists for a given picture, but also where any data has been clipped (extremes on edges of either side): that is, it does not exist and, therefore, cannot be edited.  By dragging the endpoints of the line and as well as the central one, can increased the dark/shadows, midtones and light/bright parts and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .

The U and V chroma parts show color difference components of the image. It’s useful for checking whether or not the overall chroma is too high, and also whether it’s being limited too much
Can be used to create a negative image but also 
With U (Cb), the higher value you are, the more you're on the blue primary color. If you go to the low values then you're on blue complementary color, i.e. yellow.
With V (Cr), this is the same principle but with Red and Cyan.
e.g. If you push U full blue and V full red, you get magenta. If you push U full yellow and V full Cyan then you get green.

YUV simultaneously adds to one side of the color equation while subtracting from the other.  
using YUV to do color correction can be very problematic because each curve alters the result of each other: the mutual influence between U and V often makes things tricky. You may also be careful in what you do to avoid the raise of noise (which happens very easily). Best results are obtained with little adjustments

sunset that looks uninspiring and needs some color pop especially for the rays over the hill, a subtle contrast raise while setting luma values back to the legal range without hard clipping.


====Lunapaint====

Pixel based drawing app with onion-skin animation function

 Blocking, Shading, Coloring, adding detail 

&lt;pre&gt;
b BRUSH
e ERASER

alt eyedropper 
v layer tool 

z ZOOM / MAGNIFY &lt; &gt; n 
spc panning 
m  marque 
q lasso 
w same color selection / region 
&lt;/pre&gt;

&lt;pre&gt;
, LM RM
v 
V
f  filter 
F 
.  size 

p 
,  pick color 
[] last / next color 
&lt;/pre&gt;


There is not much missing in Lunapaint to be as good as FlipBook and then you have to take into account that Flipbook is considered to be amongst the best and easiest to use animation software out there. Ok to be honest Flipbook has some nice features that require more heavy work but those aren't so much needed right away, things like camera effects, sound, smart fill, export to different movie file formats etc.

Tried Flipbook with my tablet and compared it to Luna. The feeling is the same when sketching. LunaPaint is very responsive/fluent to draw with. Just as Flipbook is, and that responsiveness is something its users have mentioned as one of the positive sides of said software.

 author was learning MUI. Some parts just have to be rewritten with proper MUI classes before new features can be added.

* add [Frame Add] / [Frame Del]
* whole animation feature is impossible to use. If you draw 2 color maybe but if you start coloring your cells then you get in trouble
* pickup the entire image as a brush, not just a selection ? And consequently remove the brush from memory when one doesn't need it anymore. can pick up a brush and put it onto a new image but cropping isn't possible, nor to load/save brushes.
* Undo is something I longed for ages in Lunapaint.
* to import into the current layer, other types of images (e.g. JPEG) besides RAW64.
* implement graphic tablet features support


**GENERAL DRAWING**

Miss it very much:
UNDO
ERASER
COLORPICKER - has to show on palette too which color got picked.
BACKGROUND COLOR -Possibility to select from &quot;New project screen&quot;

Miss it somewhat:
ICON for UNDO
ICON for ERASER
ICON for CLEAR SCREEN ( What can I say? I start over from scratch very often )
BRUSH - possibility to cut out as brush not just copy off image to brush

**ANIMATING**

Miss it very much:
NUMBER OF CELLS - Possibity to change total no. of cells during project
ANIM BRUSH - Possibility to pick up a selected part of cells into an animbrush

Miss it somewhat:
ADD/REMOVE FRAMES: Add/remove single frame

In general LunaPaint is really well done and it feels like a new DeluxePaint version. It works with my tablet. Sure there's much missing of course but things can always be added over time. So there is great potential in LunaPaint that's for sure. Animations could be made in it and maybe put together in QuickVideo, saving in .gif or .mng etc some day.


LAYERS
-Layers names don't get saved globally in animation frames
-Layers order don't change globally in an animation (perhaps as default?).

EXPORTING IMAGES
-Exporting frames to JPG/PNG gives problems with colors. (wrong colors. See my animatiopn --&gt; My robot was blue now it's &quot;gold&quot; ) I think this only happens if you have layers.
-Trying to flatten the layers before export doesn't work if you have animation frames only the one you have visible will flatten properly all other frames are destroyed. (Only one of the layers are visible on them)
-Exporting images filenames should be for example e.g. file0001, file0002...file0010 instead as of now file1, file2...file10

LOAD/SAVE (Preferences)
-Make a setting for the default &quot;Work&quot; folder.

* Destroyed colors if exported image/frame has layers 
* mystic color cycling of the selected color while stepping frames back/forth (annoying)

&lt;pre&gt;
Deluxe Paint II enhanced key shortcuts 
    NOTE: @ denotes the ALT key

    [Technique]

    F1  - Paint
    F2  - Single Colour
    F3  - Replace
    F4  - Smear
    F5  - Shade
    F6  - Cycle
    F7  - Smooth
     M  - Colour Cycle

    [Brush]

     B  - Restore
     O  - Outline
     h  - Halve brush size
     H  - Double brush size
     x  - Flip brush on X axis
     X  - Double brush size on X axis only
     y  - Flip on Y 
     Y  - Double on Y
     z  - Rotate brush 90 degrees
     Z  - Stretch

    [Stencil]

     `  - Stencil On

    [Miscellaneous]

    F9  - Info Bar
    F10 - Selection Bar
    @o  - Co-Ordinates
    @a  - Anti-alias
    @r  - Colourise
    @t  - Translucent
    TAB - Colour Cycle

    [Picture]

     L  - Load
     S  - Save
     j  - Page to Spare(Flip)
     J  - Page to Spare(Copy)
     V  - View Page
     Q  - Quit

    [General Keys]

     m  - Magnify
     &lt;  - Zoom In
     &gt;  - Zoom Out
     [  - Palette Colour Up
     ]  - Palette Colour Down
     (  - Palette Colour Left
     )  - Palette Colour Right
     ,  - Eye Dropper
     .  - Pixel / Brush Toggle
     /  - Symmetry
     |  - Co-Ordinates
    INS - Perspective Control
    +/- - Brush Size (Fine Control)
     w  - Unfilled Polygon
     W  - Filled Polygon
     e  - Unfilled Ellipse
     E  - Filled Ellipse
     r  - Unfilled Rectangle
     R  - Filled Rectangle
     t  - Type/text tool
     a  - Select Font
    u/U - Undo
     d  - Brush
     D  - Filled Non-Uniform Polygon
    f/F - Fill Options
    g/G - Grid
    h/H - Brush Size (Coarse Control)
     K  - Clear
     c  - Unfilled Circle
     C  - Filled Circle
     v  - Line
     b  - Scissor Select and Toggle
     B  - Brush
    {,} - Toggle between two background colours
&lt;/pre&gt;

====Lodepaint====

Pixel based painting artwork app

====Grafx2====

Pixel based painting artwork app aesprite like 

[https://www.youtube.com/watch?v=59Y6OTzNrhk aesprite workflow keys and tablet use], [], 


====Vector Graphics ZuneFIG====

Vector Image Editing of files .svg .ps .eps


*Objects - raise lower rotate flip aligning snapping 
*Path - unify subtract intersect exclude divide 
*Colour - fill stroke 
*Stroke - size 
*Brushes - 
*Layers - 
*Effects - gaussian bevels glows shadows 
*Text    - 
*Transform - 


 AmiFIG ([http://epb.lbl.gov/xfig/frm_introduction.html xfig manual]) 

[[File:MyScreen.png|thumb|left|alt=Showing all Windows open in AmiFIG.|All windows available to AmiFIG.]]

for drawing simple to intermediate vector graphic images for scientific and technical uses and for illustration purposes for those with talent

;Menu options
* Load - fig format but import(s) SVG
* Save - fig format but export(s) eps, ps, pdf, svg and png
* PAN = Ctrl + Arrow keys 
* Deselect all points

There is no selected object until you apply the tool, and the selected object is not highlighted.

;Metrics - to set up page and styles - first window to open on new drawings

;Tools - Drawing Primitives - set Attributes window first before clicking any Tools button(s) 
* Shapes - circles, ellipses, arcs, splines, boxes,  polygon 
* Lines - polylines
* Text &quot;T&quot; button 
* Photos - bitmaps
* Compound - Glue, Break, Scale 
* POINTs - Move, Add, Remove 
* Objects - Move, Copy, Delete, Mirror, Rotate, Paste 
use right mouse button to stop extra lines, shapes being formed and the left mouse to select/deselect tools button(s)
* Rotate - moves in 90 degree turns centered on clicked POINT of a polygon or square

;Attributes which provide change(s) to the above primitives 
* Color
* Line Width
* Line Style
* arrowheads

;Modes 
Choose from freehand, charts, figures, magnet, etc.

;Library - allows .fig clip-art to be stored 
* compound tools to add .fig(s) together

;FIG 3.2 [http://epb.lbl.gov/xfig/fig-format.html Format] as produced by xfig version 3.2.5 
&lt;pre&gt;
Landscape
Center
Inches
Letter 
100.00
Single
-2
1200 2
4 0 0 50 -1 0 12 0.0000 4 135 1050 1050 2475 This is a test.01
&lt;/pre&gt;

# change the text alignment within the textbox. I can choose left, center, or right aligned by either changing the integer in the second column from 0 (left) to 1 or 2 (center, or right). 
# The third integer in the row specifies fontcolor. For instance, 0 is black, but blue is 1 and Green3 is 13.
# The sixth integer in the bottom row specifies fontface. 0 is Times-Roman, but 16 is Helvetica (a MATLAB default).
# The seventh number is fontsize. 12 represents a 12pt fontsize. Changing the fontsize of an item really is as easy as changing that number to 20.
# The next number is the counter-clockwise angle of the text. Notice that I have changed the angle to .7854 (pi/4 rounded to four digits=45 degrees).
# twelfth number is the position according to the standard “x-axis” in Xfig units from the left. Note that 1200 Xfig units is equivalent to once inch.
# thirteenth number is the “y-position” from the top using the same unit convention as before.

* The nested text string is what you entered into the textbox.
* The “01″ present at the end of that line in the .fig file is the closing tag. For instance, a change to \100 appends a @ symbol at the end of the period of that sentence.

; Just to note there are no layers, no 3d functions, no shading, no transparency, no animation


[[#top|...to the top]]

===Audio===


# AHI uses linear panning/balance, which means that in the center, you will get -6dB. If an app uses panning, this is what you will get. Note that apps like Audio Evolution need panning, so they will have this problem.

# When using AHI Hifi modes, mixing is done in 32-bit and sent as 32-bit data to the driver. The Envy24HT driver uses that to output at 24-bit (always).

# For the Envy24/Envy24HT, I've made 16-bit and 24-bit inputs (called Line-in 16-bit, Line-in 24-bit etc.). There is unfortunately no app that can handle 24-bit recording.


====Music Mods====

Digital module (mods) trackers are music creation software using samples and sometimes soundfonts, audio plugins (VST, AU or RTAS), MIDI.

Generally, MODs are similar to MIDI in that they contain note on/off and other sequence messages that control the mod player. Unlike (most) midi files, however, they also contain sound samples that the sequence information actually plays. MOD files can have many channels (classic amiga mods have 4, corresponding to the inbuilt sound channels), but unlike MIDI, each channel can typically play only one note at once. However, since that note might be a sample of a chord, a drumloop or other complex sound, this is not as limiting as it sounds.

Like MIDI, notes will play indefinitely if they're not instructed to end. Most trackers record this information automatically if you play your music in live. If you're using manual note entry, you can enter a note-off command with a keyboard shortcut - usually Caps Lock.

In fact when considering file size MOD is not always the best option. Even a dummy song wastes few kilobytes for nothing when a simple SID tune could be few hundreds bytes and not bigger than 64kB. AHX is another small format, AHX tunes are never larger than 64kB excluding comments.

[https://www.youtube.com/watch?v=rXXsZfwgil Protrekkr] (previously aka [w:Juan_Antonio_Arguelles_Rius|NoiseTrekkr])

If Protrekkr does not start, please check if the Unit 0 has been setup in the AHI prefs and still not, go to the directory utilities/protrekkr and double click on the Protrekkr icon

*Sample
*Note - Effect 
*Track (column) - Pattern - Order

It all starts with the Sample which is used to create Note(s) in a Track (column of a tracker) 
The Note can be changed with an Effect.  A Track of Note(s) can be collected into a Pattern (section of a song) and these can be given Order to create the whole song.

Patience (notes have to be entered one at a time) or playing the bassline on a midi controller (faster - see midi section above).  Best approach is to wait until a melody popped into your head.

*Up-tempo means the track should be reasonably fast, but not super-fast. 
*Groovy and funky imply the track should have some sort of &quot;swing&quot; feel, with plenty of syncopation or off beat emphasis and a recognizable, melodic bass line. 
*Sweet and happy mean upbeat melodies, a major key and avoiding harsh sounds.
*Moody - minor key

First, create a quick bass sound, which is basically a sine wave, but can be hand drawn for a little more variance. It could also work for the melody part, too.

This is usually a bass guitar or some kind of synthesizer bass. The bass line is often forgotten by inexperienced composers, but it plays an important role in a musical piece. Together with the rhythm section the bass line forms the groove of a song. It's the glue between the rhythm section and the melodic layer of a song.

The drums are just pink noise samples, played at different frequencies to get a slightly different sound for the kick, snare, and hihats.

Instruments that fall into the rhythm category are bass drums, snares, hi-hats, toms, cymbals, congas, tambourines, shakers, etc. Any percussive instrument can be used to form part of the rhythm section.

The lead is the instrument that plays the main melody, on top of the chords. There are many instruments that can play a lead section, like a guitar, a piano, a saxophone or a flute. The list is almost endless. There is a lot of overlap with instruments that play chords. Often in one piece an instrument serves both roles. The lead melody is often played at a higher pitch than the chords.

Listened back to what was produced so far, and a counter-melody can be imagined, which can be added with a triangle wave.

To give the ends of phrases some life, you can add a solo part with a crunchy synth. By hitting random notes in the key of G, then edited a few of them.

For the climax of the song, filled out the texture with a gentle high-pitch pad… …and a grungy bass synth.


The arrow at A points at the pattern order list. As you see, the patterns don't have to be in numerical order. This song starts with pattern &quot;00&quot;, then pattern &quot;02&quot;, then &quot;03&quot;, then &quot;01&quot;, etcetera. Patterns may be repeated throughout a song.

The B arrow points at the song title. Below it are the global BPM and speed parameters. These determine the tempo of the song, unless the tempo is altered through effect commands during the song.

The C arrow points at the list of instruments. An instrument may consist of multiple samples. Which sample will be played depends on the note. This can be set in the Instrument Editing screen. Most instruments will consist of just one sample, though. The sample list for the selected instrument can be found under arrow D.

Here's a part of the main editing screen. This is where you put in actual notes. Up to 32 channels can be used, meaning 32 sounds can play simultaneously. The first six channels of pattern &quot;03&quot; at order &quot;02&quot; are shown here. The arrow at A points at the row number. The B arrow points at the note to play, in this case a C4. The column pointed at by the C arrow tells us which instrument is associated with that note, in this case instrument #1 &quot;Kick&quot;.

The column at D is used (mainly) for volume commands. In this case it is left empty which means the instrument should play at its default volume. You can see the volume column being used in channel #6.

The E column tells us which effect to use and any parameters for that effect. In this case it holds the &quot;F&quot; effect, which is a tempo command. The &quot;04&quot; means it should play at tempo 4 (a smaller number means faster).

Base pattern

When I create a new track I start with what I call the base pattern. It is worthwhile to spend some time polishing it as a lot of the ideas in the base pattern will be copied and used in other patterns. At least, that's how I work. Every musician will have his own way of working. In &quot;Wild Bunnies&quot; the base pattern is pattern &quot;03&quot; at order &quot;02&quot;.

In the section about selecting samples I talked about the four different categories of instruments: drums, bass, chords and leads. That's also how I usually go about making the base pattern. I start by making a drum pattern, then add a bass line, place some chords and top it off with a lead. This forms the base pattern from which the rest of the song will grow.


Drums

Here's a screenshot of the first four rows of the base pattern. I usually reserve the first four channels or so for the drum instruments. Right away there are a couple of tricks shown here. In the first channel the kick, or bass drum, plays some notes. Note the alternating F04 and F02 commands. The &quot;F&quot; command alters the tempo of the song and by quickly alternating the tempo; the song will get some kind of &quot;swing&quot; feel.

In the second channel the closed hi-hat plays a fairly simple pattern. Further down in the channel, not shown here, some open hi-hat notes are added for a bit of variation.

In the third and fourth channel the snare sample plays. The &quot;8&quot; command is for panning. One note is panned hard to the left and the other hard to the right. One sample is played a semitone lower than the other. This results in a cool flanging effect. It makes the snare stand out a little more in the mix.


Bass line

There are two different instruments used for the bass line. Instrument #6 is a pretty standard synthesized bass sound. Instrument #A sounds a bit like a slap bass when used with a quick fade out. By using two different instruments the bass line sounds a bit more ”human”. The volume command is used to cut off the notes. However, it is never set to zero. Setting the volume to a very small value will result in a reverb-like effect. This makes the song sound more &quot;live&quot;.

The bass line hints at the chords that will be played and the key the song will be in. In this case the key of the song is D-major, a positive and happy key.


Chords

The D major chords that are being played here are chords stabs; short sounds with a quick decay (fade out). Two different instruments (#8 and #9) are used to form the chords. These instruments are quite similar, but have a slightly different sound, panning and volume decay. Again, the reason for this is to make the sound more human. The volume command is used on some chords to simulate a delay, to achieve more of a live feel. The chords are placed off-beat making for a funky rhythm.


Lead

Finally the lead melody is added. The other instruments are invaluable in holding the track together, but the lead melody is usually what catches people's attention.

A lot of notes and commands are used here, but it looks more complex than it is. A stepwise ascending melody plays in channel 13. Channel 14 and 15 copy this melody, but play it a few rows later at a lower volume. This creates an echo effect. A bit of panning is used on the notes to create some stereo depth. Like with the bass line, instead of cutting off notes the volume is set to low values for a reverb effect. The &quot;461&quot; effect adds a little vibrato to the note, which sounds nice on sustained notes.

Those paying close attention may notice the instrument used here for the lead melody is the same as the one used for the bass line (#6 &quot;Square&quot;), except played two or three octaves higher. This instrument is a looped square wave sample. Each type of wave has its own quirks, but the square wave (shown below) is a really versatile wave form.

Song structure

Good, catchy songs are often carefully structured into sections, some of which are repeated throughout the song with small variations.

A typical pop-song structure is: Intro - Verse - Chorus - Verse - Chorus - Bridge - Chorus.

Other single sectional song structures are

&lt;pre&gt;
Strophic or AAA Song Form - oldest story telling with refrain (often title of the song) repeated in every verse section melody 
AABA Song Form - early popular, jazz and gospel fading during the 1960s 
AB or Verse/Chorus Song Form - songwriting format of choice for modern popular music since the 1960s 
Verse/Chorus/Bridge Song Form
ABAB Song Form
ABAC Song Form
ABCD Song Form
AAB 12-Bar Song Form - three four-bar lines or sub-sections 
8-Bar Song Form
16-Bar Song Form
Hybrid / Compound Song Forms
&lt;/pre&gt;

The most common building blocks are:

#INTRODUCTION(INTRO)
#VERSE
#REFRAIN
#PRE-CHORUS / RISE / CLIMB
#CHORUS
#BRIDGE
#MIDDLE EIGHT
#SOLO / INSTRUMENTAL BREAK
#COLLISION
#CODA / OUTRO
#AD LIB (OFTEN IN CODA / OUTRO)

The chorus usually has more energy than the verse and often has a memorable melody line. As the chorus is repeated the most often during the song, it will be the part that people will remember.

The bridge often marks a change of direction in the song. It is not uncommon to change keys in the bridge, or at least to use a different chord sequence. The bridge is used to build up tension towards the big finale, the last repetition of chorus.


 Playing

RCTRL:                           Play song from row 0.

LSHIFT + RCTRL:                  Play song from current row.

RALT:                            Play pattern from row 0.

LSHIFT + RALT:                   Play pattern from current row.

Left mouse on '&gt;':               Play song from row 0.

Right mouse on '&gt;':              Play song from current row.

Left mouse on '|&gt;':              Play pattern from row 0.

Right mouse on '|&gt;':             Play pattern from current row.

Left mouse on 'Edit/Record':     Edit mode on/off.

Right mouse on 'Edit/Record':    Record mode on/off.


 Editing 


LSHIFT + ESCAPE:                 Switch large patterns view on/off

TAB:                    Go to next track

LSHIFT + TAB:                    Go to prev. track

LCTRL + TAB:                    Go to next note in track

LCTRL + LSHIFT + TAB:           Go to prev. note in track

SPACE:                           Toggle Edit mode On &amp; Off

(Also stop if the song is being played)

SHIFT SPACE:                     Toggle Record mode On &amp; Off

(Wait for a key note to be pressed

or a midi in message to be received)

DOWN ARROW:                      1 Line down

UP ARROW:                        1 Line up

LEFT ARROW:                      1 Row left

RIGHT ARROW:                     1 Row right

PREV. PAGE:                      16 Arrows Up

NEXT PAGE:                       16 Arrows Down

HOME / END:                      Top left / Bottom right of pattern

LCTRL + HOME / END:              First / last track

F5, F6, F7, F8, F9:              Jump to 0, 1/4, 2/4, 3/4, 4/4 lines of the patterns

+ - (Numeric keypad):           Next / Previous pattern

LCTRL + LEFT / RIGHT:           Next / Previous pattern

LCTRL + LALT + LEFT / RIGHT:    Next / Previous position

LALT + LEFT / RIGHT:           Next / Previous instrument

LSHIFT + M:                      Toggle mute state of the current channel

LCTRL + LSHIFT + M:             Solo the current track / Unmute all

LSHIFT + F1 to F11:              Select a tab/panel

LCTRL + 1 to 4:                 Select a copy buffer


 Tracking 

1st and 2nd keys rows:           Upper octave row

3rd and 4th keys rows:           Lower octave row

RSHIFT:                          Insert a note off

/ and * (Numeric keypad)

or F1 F2:                        -1 or +1 octave

INSERT / BACKSPACE:              Insert or Delete a line in current track

or current selected block.

LSHIFT + INSERT / BACKSPACE:     Insert or Delete a line in current pattern

DELETE (NOT BACKSPACE):          Empty a column or a selected block.


 Blocks

(Blocks can also be selected with the mouse by holding the right button and scrolling the pattern with the mouse wheel).


LCTRL + A:          Select entire current track

LCTRL + LSHIFT + A: Select entire current pattern

LALT + A:          Select entire column note in a track

LALT + LSHIFT + A: Select all notes of a track

LCTRL + X:          Cut the selected block and copy it into the block-buffer

LCTRL + C:          Copy the selected block into the block-buffer

LCTRL + V:          Paste the data from the block buffer into the pattern

LCTRL + I:          Interpolate selected data from the first to the last row of a selection

LSHIFT + ARROWS

PREV. PAGE

NEXT PAGE: Select a block

LCTRL + R:          Randomize the select columns of a selection, works similar to CTRL + I (interpolating them)

LCTRL + U:          Transpose the note of a selection to 1 seminote higher

LCTRL + D:          Transpose the note of a selection to 1 seminote lower

LCTRL + LSHIFT + U: Transpose the note of a selection to 1 seminote higher (only for the current instrument)

LCTRL + LSHIFT + D: Transpose the note of a selection to 1 seminote lower  (only for the current instrument)

LCTRL + H:          Transpose the note of a selection to 1 octave higher

LCTRL + L:          Transpose the note of a selection to 1 octave lower

LCTRL + LSHIFT + H: Transpose the note of a selection to 1 octave higher (only for the current instrument)

LCTRL + LSHIFT + L: Transpose the note of a selection to 1 octave lower (only for the current instrument)

LCTRL + W:          Save the current selection into a file


 Misc 


LALT + ENTER:     Switch between full screen / windowed mode

LALT + F4:        Exit program (Windows only)

LCTRL + S:         Save current module

LSHIFT + S:         Switch top right panel to synths list

LSHIFT + I:         Switch top right panel to instruments list


&lt;pre&gt;
C-x   xh xx xx hhhh             Volume 
B-x   xh xx xx hhhh             Jump to 
A#x  xh xx xx hhhh hhhh   Slide 
F-x    xh xx xx hhhh            Tempo 
D-x   xh xx xx hhhh             Pattern Break 
G#x  xh xx xx hhhh
&lt;/pre&gt;

h Hex 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13

d Dec 01 02 03 04 05 06 07 08 09 10  11 12 13 14 15 16 17 18 19

The Set Volume command: C. Input a note, then move the cursor to the effects command column and type a C. Play the pattern, and you shouldn't be able to hear the note you placed the C by. This is because the effect parameters are 00. Change the two zeros to a 40(Hex)/64(Dec), depending on what your tracker uses. Play back the pattern again, and the note should come in at full volume.

The Position Jump command next. This is just a B followed by the position in the playing list that you want to jump to. One thing to remember is that the playing list always starts at 0, not 1. This command is usually in Hex.

Onto the volume slide command: A. This is slightly more complex (much more if you're using a newer tracker, if you want to achieve the results here, then set slides to Amiga, not linear), due to the fact it depends on the secondary tempo. For now set a secondary tempo of 06 (you can play around later), load a long or looped sample and input a note or two. A few rows after a note type in the effect command A. For the parameters use 0F. Play back the pattern, and you should notice that when the effect kicks in, the sample drops to a very low volume very quickly. Change the effect parameters to F0, and use a low volume command on the note. Play back the pattern, and when the slide kicks in the volume of the note should increase very quickly.
This because each part of the effect parameters for command A does a different thing. The first number slides the volume up, and the second slides it down. It's not recommended that you use both a volume up and volume down at the same time, due to the fact the tracker only looks for the first number that isn't set to 0. If you specify parameters of 8F, the tracker will see the 8, ignore the F, and slide the volume up. Using a slide up and down at same time just makes you look stupid. Don't do it...

The Set Tempo command: F, is pretty easy to understand. You simply specify the BPM (in Hex) that you want to change to. One important thing to note is that values of lower than 20 (Hex) sets the secondary tempo rather than the primary.

Another useful command is the Pattern Break: D. This will stop the playing of the current pattern and skip to the next one in the playing list. By using parameters of more than 00 you can also specify which line to begin playing from.

Command 3 is Portamento to Note. This slides the currently playing note to another note, at a specified speed. The slide then stops when it reaches the desired note. 
&lt;pre&gt;
   C-2 1 000 - Starts the note playing
   ---      000
   C-3    330 - Starts the slide to C-3 at a speed of 30.
   ---     300 - Continues the slide
   ---     300 - Continues the slide
&lt;/pre&gt;
Once the parameters have been set, the command can be input again without any parameters, and it'll still perform the same function unless you change the parameters. This memory function allows certain commands to function correctly, such as command 5, which is the Portamento to Note and Volume Slide command. Once command 3 has been set up command 5 will simply take the parameters from that and perform a Portamento to Note. Any parameters set up for command 5 itself simply perform a Volume Slide identical to command A at the same time as the Portamento to Note.

This memory function will only operate in the same channel where the original parameters were set up.
There are various other commands which perform two functions at once. They will be described as we come across them.

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  00

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  02

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  05

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  08

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0A

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0D

C-3  04  ..  ..  09  10 ---&gt; C-3  04  ..  ..  09  10

(You can also switch on the Slider Rec to On, and perform parameter-live-recording, such as cutoff transitions, resonance or panning tweaking, etc..)  Note: this command only works for volume/panning and fx datas columns.


The next command we'll look at is the Portamento up/down: 1 and 2. Command 1 slides the pitch up at a specified speed, and 2 slides it down. This command works in a similar way to the volume slide, in that it is dependent on the secondary tempo. Both these commands have a memory dependent on each other, if you set the slide to a speed of 3 with the 1 command, a 2 command with no parameters will use the speed of 3 from the 1 command, and vice versa.

Command 4 is Vibrato. Vibrato is basically rapid changes in pitch, just try it, and you'll see what I mean. Parameters are in the format of xy, where x is the speed of the slide, and y is the depth of the slide. One important point to remember is to keep your vibratos subtle and natural so a depth of 3 or less and a reasonably fast speed, around 8, is usually used. Setting the depth too high can make the part sound out of tune from the rest.
Following on from command 4 is command 6. This is the Vibrato and Volume Slide command, and it has a memory like command 5, which you already know how to use.

Command 7 is Tremolo. This is similar to vibrato. Rather than changing the pitch it slides the volume. The effect parameters are in exactly the same format.   vibrato effect (0x1dxy) x = speed y = depth (can't be used if arpeggio (0x1b) is turned on) 

&lt;pre&gt;
 C-7 00 .. .. 1B37 &lt;-  Turn Arpeggio effect on
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B38 &lt;- Change datas
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B00 &lt;- Turn it off
&lt;/pre&gt;

Command 9 is Sample Offset. This starts the playback of the sample from a different place than the start. The effect parameters specify the sample offset, but only very roughly. Say you have a sample which is 8765(Hex) bytes long, and you wanted it to play from position 4321(Hex). The effect parameter could only be as accurate as the 43 part, and it would ignore the 21.

Command B is the Playing List/Order Jump command. The parameters specify the position in the Playing List/Order to jump to. When used in conjunction with command D you can specify the position and the line to play from.

Command E is pretty complex, as it is used for a lot of different things, depending on what the first parameter is. Let's take a trip through each effect in order.
Command E0 controls the hardware filter on an Amiga, which, as a low pass filter, cuts off the highest frequencies being played back. There are very few players and trackers on other system that simulate this function, not that you should need to use it. The second parameter, if set to 1, turns on the filter. If set to 0, the filter gets turned off.

Commands E1/E2 are Fine Portamento Up/Down. Exactly the same functions as commands 1/2, except that they only slide the pitch by a very small amount. These commands have a memory the same as 1/2 as well.

Command E3 sets the Glissando control. If parameters are set to 1 then when using command 3, any sliding will only use the notes in between the original note and the note being slid to. This produces a somewhat jumpier slide than usual. The best way to understand is to try it out for yourself. Produce a slow slide with command 3, listen to it, and then try using E31.

Command E4 is the Set Vibrato Waveform control. This command controls how the vibrato command slides the pitch. Parameters are 0 - Sine, 1 - Ramp Down (Saw), 2 - Square. By adding 4 to the parameters, the waveform will not be restarted when a new note is played e.g. 5 - Sine without restart.

Command E5 sets the Fine Tune of the instrument being played, but only for the particular note being played. It will override the default Fine Tune for the instrument. The parameters range from 0 to F, with 0 being -8 and F being +8 Fine Tune. A parameter of 8 gives no Fine Tune. If you're using a newer tracker that supports more than -8 to +8 e.g. -128 to +128, these parameters will give a rough Fine Tune, accurate to the nearest 16.

Command E6 is the Jump Loop command. You mark the beginning of the part of a pattern that you want to loop with E60, and then specify with E6x the end of the loop, where x is the number of times you want it to loop.

Command E7 is the Set Tremolo Waveform control. This has exactly the same parameters as command E4, except that it works for Tremolo rather than Vibrato.

Command E9 is for Retriggering the note quickly. The parameter specifies the interval between the retrigs. Use a value of less than the current secondary tempo, or else the note will not get retrigged.

Command EA/B are for Fine Volume Slide Up/Down. Much the same as the normal Volume Slides, except that these are easier to control since they don't depend on the secondary tempo. The parameters specify the amount to slide by e.g. if you have a sample playing at a volume of 08 (Hex) then the effect EA1 will slide this volume to 09 (Hex). A subsequent effect of EB4 would slide this volume down to 05 (Hex).

Command EC is the Note Cut. This sets the volume of the currently playing note to 0 at a specified tick. The parameters should be lower than the secondary tempo or else the effect won't work.

Command ED is the Note Delay. This should be used at the same time as a note is to be played, and the parameters will specify the number of ticks to delay playing the note. Again, keep the parameters lower than the secondary tempo, or the note won't get played!

Command EE is the Pattern Delay. This delays the pattern for the amount of time it would take to play a certain number of rows. The parameters specify how many rows to delay for.

Command EF is the Funk Repeat command. Set the sample loop to 0-1000. When EFx is used, the loop will be moved to 1000- 2000, then to 2000-3000 etc. After 9000-10000 the loop is set back to 0- 1000. The speed of the loop &quot;movement&quot; is defined by x. E is two times as slow as F, D is three times as slow as F etc. EF0 will turn the Funk Repeat off and reset the loop (to 0-1000).

effects 0x41 and 0x42 to control the volumes of the 2 303 units

There is a dedicated panel for synth parameter editing with coherent sections (osc, filter modulation, routing, so on) the interface is much nicer, much better to navigate with customizable colors, the reverb is now customizable (10 delay lines), It accepts newer types of Waves (higher bit rates, at least 24). Has a replay routine.

It's pretty much your basic VA synth. The problem isn't with the sampler being to high it's the synth is tuned two octaves too low, but if you want your samples tuned down just set the base note down 2 octaves (in the instrument panel).

so the synth is basically divided into 3 sections from left to right: oscillators/envelopes, then filter and LFO's, and in the right column you have mod routings and global settings.

for the oscillator section you have two normal oscillators (sine, saw, square, noise), the second of which is tunable, the first one tunes with the key pressed. Attached to OSC 1 is a sub-oscillator, which is a sawtooth wave tuned one octave down. The phase modulation controls the point in the duty cycle at which the oscillator starts. The ADSR envelope sliders (grouped with oscs) are for modulation envelope 1 and 2 respectively. you can use the synth as a sampler by choosing the instrument at the top.

In the filter column, the filter settings are: 1 = lowpass, 2 = highpass, 3 = off. cutoff and resonance. For the LFOs they are LFO 1 and LFO 2, the ADSR sliders in those are for the LFO itself.

For the modulation routings you have ENV 1, LFO 1 for the first slider and ENV 2, LFO 2 for the second, you can cycle through the individual routings there, and you can route each modulation source to multiple destinations of course, which is another big plus for this synth. Finally the glide time is for portamento and master volume, well, the master volume... it can go quite loud.

The sequencer is changed too, It's more like the one in AXS if you've used that, where you can mute tracks to re-use patterns with variation.


&lt;pre&gt;
Support for the following modules formats:
669 (Composer 669, Unis 669), 
AMF (DSMI Advanced Module Format), 
AMF (ASYLUM Music Format V1.0), 
APUN (APlayer), DSM (DSIK internal format), 
FAR (Farandole Composer), 
GDM (General DigiMusic), 
IT (Impulse Tracker), 
IMF (Imago Orpheus), 
MOD (15 and 31 instruments), 
MED (OctaMED), 
MTM (MultiTracker Module editor), 
OKT (Amiga Oktalyzer), 
S3M (Scream Tracker 3), 
STM (Scream Tracker), 
STX (Scream Tracker Music Interface Kit), 
ULT (UltraTracker), 
UNI (MikMod), 
XM (FastTracker 2),
Mid (midi format via timidity)
&lt;/pre&gt;


Possible plugin options include [http://lv2plug.in/ LV2],


====Midi - Musical Instrument Digital Interface====

A midi file typically contains music that plays on up to 16 channels (as per the midi standard), but many notes can simultaneously play on each channel (depending on the limit of the midi hardware playing it).

'''Timidity'''

Although usually already installed, you can uncompress the [http://www.libsdl.org/projects/SDL_mixer/ timidity.tar.gz (14MB)] into a suitable drawer like below's SYS:Extras/Audio/ 
 assign timidity: SYS:Extras/Audio/timidity
added to SYSːs/User-Startup

'''WildMidi playback'''


'''Audio Evolution 4 (2003) 4.0.23 (from 2012)'''


*Sync Menu    - CAMD Receive, Send checked 
*Options Menu - MIDI Machine Control - Midi Bar Display - Select CAMD MIDI in / out - Midi Remote Setup 


MCB Master Control Bus 
*Sending a MIDI start-command and a Song Position Pointer, you can synchronize audio with an external MIDI sequencer (like B&amp;P). 
*B&amp;P Receive, start AE, add AudioEvolution.ptool in Bars&amp;Pipes track, press play / record in AE then press play in Pipes 
*CAMD Receive, receive MIDI start or continue commands via camd.library sync to AE 


*MIDI Machine Control
*Midi Bar Display 
*Select CAMD MIDI in / out
*Midi Remote Setup - open requester for external MIDI controllers to control app mixer and transport controls cc remotely 
 Channel   - mixer(vol, pan, mute, solo), eq, aux, fx, 
 Subgroup  - Volume, Mute, Solo 
 Transport - Start, End, Play, Stop, Record, Rewind, Forward 
 Misc      - Master vol., Bank Down, Bank up 


&lt;pre&gt;
q        - quit 

First 3 already opened when AE started 
F1       - timeline window
F2       - mixer 
F3       - control 
F4       - subgroups 
F5       - aux returns 
F6       - sample list 

i        - Load sample to use 

space    - start/stop play 
b        - reset time 0:00


s        - split mode 
r        - open recording window 
a        - automation edit mode with p panning, m mute and v volume 


[ / ]    - zoom in / out 
:        - previous track
*        - next track 

x c v f  - cut copy paste cross-fade 
g        - snap grid 


&lt;/pre&gt;


 '''[http://bnp.hansfaust.de/ Bars n Pipes sequencer]'''

 BarsnPipes debug ... in shell 

Menu (right mouse)  
*Song        - Songs load and save in .song format but option here to load/save Midi_Files .mid in FORMAT0 or FORMAT1 
*Track       - 
*Edit        -
*Tool        - 
*Timing      - SMTPE Synchronizing 
*Windows     - 
*Preferences - Multiple MIDI-in option 

Windows (some of these are usually already opened when Bars n Pipes starts up for the first time) 
*Workflow -&gt; Tracks, .... Song Construction, Time-line Scoring, Media Madness, Mix Maestro, 
*Control  -&gt; Transport (or mini one), Windows (which collects all the Windows icons together-shortcut), .... Toolbox, Accessories, Metronome, 

Once you have your windows placed on the screen that suits your workflow, Song -&gt; Save as Default will save the positions, colors, icons, etc as you'd like them 

If you need a particular setup of Tracks, Tools, Tempos etc, you save them all as a new song you can load each time 

Right mouse menu -&gt; Preferences -&gt; Environment... -&gt; ScreenMode  - Linkages for Synch (to Slave) usbmidi.out.0 and Send (Master) usbmidi.in.0 - Clock MTC 


'''Tracks'''

#Double-click on B&amp;P's icon. B&amp;P will then open with an empty Song. You can also double-click on a song icon to open a song in B&amp;P.
#Choose a track. The B&amp;P screen will contain a Tracks Window with a number of tracks shown as pipelines (Track 1, Track 2, etc...). To choose a track, simply click on the gray box to show an arrow-icon to highlight it. This icon show whether a track is chosen or not. To the right of the arrow-icon, you can see the icon for the midi-input. If you double-click on this icon you can change the MIDI-in setup.
#Choose Record for the track. To the right of the MIDI-input channel icon you can see a pipe. This leads to another clickable icon with that shows either P, R or M. This stands for Play, Record or Merge. To change the icon, simply click on it. If you choose P, this track can only play the track (you can't record anything). If you choose R, you can record what you play and it overwrites old stuff in the track. If you choose M, you merge new records with old stuff in the track. Choose R now to be able to make a record.
#Chose MIDI-channel. On the most right part of the track you can see an icon with a number in it. This is the MIDI-channel selector. Here you must choose a MIDI-channel that is available on your synthesizer/keyboard. If you choose General MIDI channel 10, most synthesizer will play drum sounds. To the left of this icon is the MIDI-output icon. Double-click on this icon to change the MIDI-output configuration.
#Start recording. The next step is to start recording. You must then find the control buttons (they look like buttons on a CD-player). To be able to make a record. you must click on the R icon. You can simply now press the play button (after you have pressed the R button) and play something on you keyboard. To playback your composition, press the Play button on the control panel.
#Edit track. To edit a track, you simply double click in the middle part of a track. You will then get a new window containing the track, where you can change what you have recorded using tools provided. Take also a look in the drop-down menus for more features.


Videos to help understand [https://www.youtube.com/watch?v=A6gVTX-9900 small intro], [https://www.youtube.com/watch?v=abq_rUTiSA4&amp;t=3s Overview], [https://www.youtube.com/watch?v=ixOVutKsYQo Workplace Setup CC PC Sysex], [https://www.youtube.com/watch?v=dDnJLYPaZTs Import Song], [https://www.youtube.com/watch?v=BC3kkzPLkv4 Tempo Mapping], [https://www.youtube.com/watch?v=sd23kqMYPDs ptool Arpeggi-8], [https://www.youtube.com/watch?v=LDJq-YxgwQg  PlayMidi Song], [https://www.youtube.com/watch?v=DY9Pu5P9TaU Amiga Midi], [https://www.youtube.com/watch?v=abq_rUTiSA4 Learning Amiga bars and Pipes], 

Groups like [https://groups.io/g/barsnpipes/topics this] could help 


'''Tracks window'''

* blue &quot;1 2 3 4 5 6 7 8 Group&quot; and transport tape deck VCR-type controls
* Flags 
* [http://theproblem.alco-rhythm.com/org/bp.html Track 1, Track2, to Track 16, on each Track there are many options that can be activated] 

Each Track has a 

*Left LHS  - Click in grey box to select what Track to work on, Midi-In ptool icon should be here (5pin plug icon), and many more from the Toolbox on the Input Pipeline 
*Middle    - (P, R, M) Play, Record, Merge/Multi before the sequencer line and a blue/red/yellow (Thru Mute Play) Tap 
*Right RHS - Output pipeline, can have icons placed uopn it with the final ptool icon(s) being the 5pin icon symbol for Midi-OUT 

Clogged pipelines may need Esc pressed several times 


'''Toolbox (tools affect the chosen pipeline)'''

After opening the Toolbox window you can add extra Tools (.ptool) for the pipelines like keyboard(virtual), midimonitor, quick patch, transpose, triad, (un)quantize, feedback in/out, velocity etc
 right mouse -&gt; Toolbox menu option -&gt; Install Tool... and navigate to Tool drawer (folder) and select requried .ptool 

Accompany B tool to get some sort of rythmic accompaniment, Rythm Section and Groove Quantize are examples of other tools that make use of rythms
[https://aminet.net/search?query=bars Bars &amp; Pipes pattern format .ptrn] for drawer (folder). Load from the Menu as Track or Group 


'''Accessories (affect the whole app)''' 

Accessories -&gt; Install... and goto the Accessories drawer for .paccess like adding ARexx scripting support 


'''Song Construction'''
&lt;pre&gt;
F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Duplicator 
F5  Eraser 
F6  Toolpad 
F7  Bounding box 
F8  Lock to A-B-A 

A-B-A strip, section, edit flags, white boxes, 

&lt;/pre&gt;


Bars&amp;Pipes Professional offers three track formats; basic song tracks, linear tracks — which don't loop — and finally real‑time tracks. The difference between them is that both song and linear tracks respond to tempo changes, while real‑time tracks use absolute timing, always trigger at the same instant regardless of tempo alterations 

'''Tempo Map'''

F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Eraser 
F5  Curve 
F6  Toolpad 


Compositions

Lyrics, Key, Rhythm, Time Signature 

'''Master Parameters'''

Key, Scale/Mode

'''Track Parameters'''

Dynamics 


'''Time-line Scoring'''


'''Media Madness'''


'''Mix Maestro'''


*ACCESSORIES         Allows the importation of other packages and additional modules 
*CLIPBOARD           Full cut, copy and paste operations, enabling user‑definable clips to be shared between tracks.
*INFORMATION         A complete rundown on the state of the current production and your machine.
*MASTER PARAMETERS   Enables global definition of time signatures, lyrics, scales, chords, dynamics and rhythm changes.
*MEDIA MADNESS       A complete multimedia sequencer which allows samples, stills, animation, etc 
*METRONOME           Tempo feedback via MIDI, internal Amiga audio and colour cycling — all three can be mixed and matched as required.
*MIX MAESTRO         Completely automated mixdown with control for both volume and pan. All fader alterations are memorised by the software 
*RECORD ACTIVATION   Complete specification of the data to be recorded/merged. Allows overdubbing of pitch‑bend, program changes, modulation etc
*SET FLAGS           Numeric positioning of location and edit flags in either SMPTE or musical time 
*SONG CONSTRUCTION   Large‑scale cut and paste of individual measures, verses or chorus, by means of bounding box and drag‑n‑drop mouse selections
*TEMPO MAP           Tempo change using a variety of linear and non‑linear transition curves 
*TEMPO PALETTE       Instant tempo changes courtesy of four user‑definable settings.
*TIMELINE SCORING    Sequencing of a selection of songs over a defined period — ideal for planning an entire set for a live performance.
*TOOLBOX             Selection screen for the hundreds of signal‑processing tools available 
*TRACKS              Opens the main track window to enable recording, editing and the use of tools.
*TRANSPORT           Main playback control window, which also provides access to user‑ defined flags, loop and punch‑in record modes.


Bars and Pipes Pro 2.5 is using internal 4-Byte IDs, to check which kind of data are currently processed.
Especially in all its files the IDs play an important role. The IDs are stored into the file in the same order they are laid out in the memory.

In a Bars 'N' Pipes file (no matter which kind) the ID &quot;NAME&quot; (saved as its ANSI-values) is stored on a big endian system (68k-computer) as &quot;NAME&quot;. On a little endian system (x86 PC computer) as &quot;EMAN&quot;.  The target is to make the AROS-BnP compatible to songs, which were stored on a 68k computer (AMIGA).

If possible, setting MIDI channels for Local Control for your keyboard 

http://www.fromwithin.com/liquidmidi/archive.shtml


MIDI files are essentially a stream of event data. An event can be many things, but typically &quot;note on&quot;, &quot;note off&quot;, &quot;program change&quot;, &quot;controller change&quot;, or messages that instruct a MIDI compatible synth how to play a given bit of music.

* Channel     - 1 to 16 -
* Messages    - PC presets, CC effects like delays, reverbs,  etc 
* Sequencing  - MIDI instruments, Drums, Sound design, 
* Recording   - 
* GUI         - Piano roll or Tracker, Staves and Notes 

MIDI events/messages like step entry e.g. Note On, Note Off 

MIDI events/messages like PB, PC, CC, Mono and Poly After-Touch, Sysex, etc 

MIDI sync - Midi Clocks (SPS Measures), Midi Time Code (h, m, s and frames) SMPTE 

Individual track editing with audition edits so easier to test any changes. Possible to stop track playback, mix clips from the right edit flag and scroll the display using arrow keys. 

Step entry, to extend a selected note hit the space bar and the note grows accordingly. Ability to cancel mouse‑driven edits by simply clicking the right mouse button — at which point everything snaps back into its original form. Lyrics can now be put in with syllable dividers, even across an entire measure or section. Autoranging when you open a edit window, the notes are automatically displayed — working from the lowest upwards. 

Flag editing, shift‑click on a flag immediately open the bounds window, ready for numeric input. Ability to cancel edits using the right‑hand mouse button, plus much improved Bounding Box operations.

Icons other than the BarsnPipes icon -&gt; PUBSCREEN=BarsnPipes (cannot choose modes higher than 8bit 256 colors)

Preferences -&gt; Menu in Tracks window - Send MIDI defaults OFF 

Prefs -&gt; Environment -&gt; screenmode (saved to BarsnPipes.prefs binary file) 

Customization -&gt; pics in gui drawer (folder) - 


Can save as .song files and .mid General Midi 

SMF is a “Standard Midi File”  ([http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html SMF0, SMF1 and SMF2]), [https://github.com/stump/libsmf libsmf], [https://github.com/markc/midicomp MIDIcomp], [https://github.com/MajicDesigns/MD_MIDIFile C++ src], [], [https://github.com/newdigate/midi-smf-reader Midi player], 

* SMF0        All MIDI data is stored in one track only, separated exclusively by the MIDI channel.
* SMF1        The MIDI data is stored in separate tracks/channels.
* SMF2 (rarely used) The MIDI data is stored in separate tracks, which are additionally wrapped in containers, so it's possible to have e.g. several tracks using the same MIDI channels.


Would it be possible to enrich Bars N’Pipes with software synth and sample support along with audio recording and mastering tools like in the named MAC or PC music sequencers?
On the classic AMIGA-OS this is not possible because of missing CPU-power. The hardware of the classic AMIGA is not further developed. So we must say (unfortunately) that those dreams can’t become reality

BarsnPipes is best used with external MIDI-equipment. This can be a keyboard or synthesizer with MIDI-connectors. 

&lt;pre&gt;
MIDI can control 16 channels 
There are USB-MIDI-Interfaces on the market with 16 independent MIDI-lines (multi-port), which can handle 16 MIDI devices independently – 16×16 = 256 independent MIDI-channels or instruments 
handle up to 16 different USB-MIDI-Interfaces (multi-device). That is: 16X16X16 = 4096 independent MIDI-channels – theoretically 
&lt;/pre&gt;

&lt;pre&gt;
Librarian MIDI SYStem EXplorer (sysex) - PatchEditor and used to be supplied as a separate program like PatchMeister but currently not at present 
It should support MIDI.library (PD), BlueRibbon.library (B&amp;P), TriplePlayPlus, and CAMD.library (DeluxeMusic) and 
MIDI information from a device's user manual and configure a custom interface to access parameters for all MIDI products connected to the system 
Supports ALL MIDI events and the Patch/Librarian data is stored in MIDI standard format 
Annette M.Crowling, Missing Link Software, Inc.
&lt;/pre&gt;


Composers
&lt;pre&gt;
[https://x.com/hirasawa/status/1403686519899054086 Susumu Hirasawa] 

&lt;/pre&gt;


&lt;pre&gt;
1988 Todor Fay and his wife Melissa Jordan Gray, who founded the Blue Ribbon Inc
1992 Bars&amp;Pipes Pro published 
November 2000, Todor Fay announcement to release the sourcecode of Bars&amp;Pipes Pro 2.5c beta
end of May 2001, the source of the main program and the sources of some tools and accessories were in a complete and compileable state 
end of October 2009 stop further development of BarsnPipes New for now on all supported systems and made freeware 
2013 Alfred Faust diagnosed with incureable illness, called „Myastenia gravis“ (weak muscles) 
&lt;/pre&gt;


 Protrekkr

How to use Midi In/Out in Protrekkr ?

First of all, midi in &amp; out capabilities of this program are rather limited.

# Go to Misc. Setup section and select a midi in or out device to use (ptk only supports one device at a time).
# Go to instrument section, and select a MIDI PRG (the default is N/A, which means no midi program selected).
# Go to track section and here you can assign a midi channel to each track of ptk.
# Play notes :]. Note off works. F'x' note cut command also works too, and note-volume command (speed) is supported.

Also, you can change midicontrollers in the tracker, using '90' in the panning row:

&lt;pre&gt;
    C-3 02 .. .. 0000....


    --- .. .. 90 xxyy.... &lt;&lt; This will set the value 
    --- .. .. .. 0000....    of the controller n.'xx' to 'yy' (both in hex)
    --- .. .. .. 0000....
&lt;/pre&gt;

So &quot;--- .. .. 90 2040....&quot; will set the controller number $20(32) to $40(64).

You will need the midi implementation table of your gear to know what you can change with midi controller messages.

 N.B. Not all MIDI devices are created equal!

Although the MIDI specification defines a large range of MIDI messages of various kinds, not every MIDI device is required to work in exactly the same way and respond to all the available messages and ways of working. For example, we don't expect a wind synthesiser to work in the same way as a home keyboard.

Some devices, the older ones perhaps, are only able to respond to a single channel. With some of those devices that channel can be altered from the default of 1 (probably) to another channel of the 16 possible.

Other devices, for instance monophonic synthesisers, are capable of producing just one note at a time, on one MIDI channel. Others can produce many notes spread across many channels.

Further devices can respond to, and transmit, &quot;breath controller&quot; data (MIDI controller number 2 (CC#2)) others may respond to the reception of CC#2 but not be able to create and to send it.

A controller keyboard may be capable of sending &quot;expression pedal&quot; data, but another device may not be capable of responding to that message.

Some devices just have the basic GM sound set. The &quot;voice&quot; or &quot;instrument&quot; is selected using a &quot;Program Change&quot; message on its own.

Other devices have a greater selection of voices, usually arranged in &quot;banks&quot;, and the choice of instrument is made by responding to &quot;Bank Select MSB&quot; (MIDI controller 0 (CC#0)), others use &quot;Bank Select LSB&quot; (MIDI controller number 32 (CC#32)), yet others use both MSB and LSB sent one after the other, all followed by the Program Change message. The detailed information about all the different voices will usually be available in a published MIDI Data List.


 MIDI Implementation Chart

But in the User Manual there is sometimes a summary of how the device works, in terms of MIDI, in the chart at the back of the manual, the MIDI Implementation Chart.

If you require two devices to work together you can compare the two implementation charts to see if they are &quot;compatible&quot;. In order to do this we will need to interpret that chart.

The chart is divided into four columns headed &quot;Function&quot;, &quot;Transmitted&quot; (or &quot;Tx&quot;), &quot;Received&quot; (or &quot;Rx&quot;), or more correctly &quot;Recognised&quot;, and finally, &quot;Remarks&quot;.

&lt;pre&gt;
The left hand column defines which MIDI functions are being described.
The 2nd column defines what the device in question is capable of transmitting to another device.
The 3rd column defines what the device is capable of responding to.
The 4th column is for explanations of the values contained within these previous two columns.
&lt;/pre&gt;

There should then be twelve sections, with possibly a thirteenth containing extra &quot;Notes&quot;. Finally there should be an explanation of the four MIDI &quot;modes&quot; and what the &quot;X&quot; and the &quot;O&quot; mean.
&lt;pre&gt;
Mode 1: Omni On, Poly; 
Mode 2: Omni On, Mono; 
Mode 3: Omni Off, Poly; 
Mode 4: Omni Off, Mono.
&lt;/pre&gt;
O means &quot;yes&quot; (implemented), X means &quot;no&quot; (not implemented).

Sometimes you will find a row of asterisks &quot;**************&quot;, these seem to indicate that the data is not applicable in this case. Seen in the transmitted field only (unless you've seen otherwise).

Lastly you may find against some entries an asterisk followed by a number e.g. *1, these will refer you to further information, often on a following page, giving more detail.

Basic Channel
But the very first set of boxes will tell us the &quot;Basic Channel(s)&quot; that the device sends or receives on. 
&quot;Default&quot; is what happens when the device is first turned on, &quot;changed&quot; is what a switch of some kind may allow the device to be set to. 
For many devices e.g. a GM sound module or a home keyboard, this would be 1-16 for both. That is it can handle sending and receiving on all MIDI channels.

On other devices, for example a synthesiser, it may by default only work on channel 1. But the keyboard could be &quot;split&quot; with the lower notes e.g. on channel 2. If the synth has an arppegiator, this may be able to be set to transmit and or receive on yet another channel.
So we might see the default as &quot;1&quot; but the changed as &quot;1-16&quot;.

Modes.
We need to understand Omni On and Off, and Mono and Poly, then we can decipher the four modes.

But first we need to understand that any of these four Mode messages can be sent to any MIDI channel. They don't necessarily apply to the whole device.

If we send an &quot;Omni On&quot; message (CC#125) to a MIDI channel of a device, we are, in effect, asking it to respond to e.g. a Note On / Off message pair, received on any of the sixteen channels. Sound strange? Read it again. Still strange? It certainly is. We normally want a MIDI channel to respond only to Note On / Off messages sent on that channel, not any other. In other words, &quot;Omni Off&quot;.

So &quot;Omni Off&quot; (CC#124) tells a channel of our MIDI device to respond only to messages sent on that MIDI channel.

&quot;Poly&quot; (CC#127) is for e.g. a channel of a polyphonic sound module, or a home keyboard, to be able to respond to many simultaneous Note On / Off message pairs at once and produce musical chords.

&quot;Mono&quot; (CC#126) allows us to set a channel to respond as if it were e.g. a flute or a trumpet, playing just one note at a time. If the device is capable of it, then the overlapping of notes will produce legato playing, that is the attack portion of the second note of two overlapping notes will be removed resulting in a &quot;smoother&quot; transition.

So a channel with a piano voice assigned to it will have Omni Off, Poly On (Mode 3), a channel with a saxophone voice assigned could be Omni Off, Mono On (Mode 4).

We call these combinations the four modes, 1 to 4, as defined above. 
Most modern devices will have their channels set to Mode 3 (Omni Off, Poly) but be switchable, on a per channel basis, to Mode 4 (Omni Off, Mono).

This second section of data will include first its default value i.e. upon device switch on. Then what Mode messages are acceptable, or X if none.

Finally, in the &quot;Altered&quot; field, how a Mode message that can't be implemented will be interpreted. Usually there will just be a row of asterisks effectively meaning nothing will be done if you try to switch to an unimplemented mode.

Note Number
&lt;pre&gt;
The next row will tell us which MIDI notes the device can send or receive, normally 0-127.
The second line, &quot;True Voice&quot; has the following in the MIDI specification: 
&quot;Range of received note numbers falling within the range of true notes produced by the instrument.&quot;
My interpretation is that, for instance, a MIDI piano may be capable of sending all MIDI notes (0 to 127) by transposition, but only responding to the 88 notes (21 to 108) of a real piano. 
&lt;/pre&gt;

Velocity
This will tell us whether the device we're looking at will handle note velocity, and what range from 1-127, or maybe just 64, it transmits or will recognise. So usually &quot;O&quot; plus a range or &quot;X&quot; for not implemented.

After touch
This may have one or two lines two it.
If a one liner the either &quot;O&quot; or &quot;X&quot;, yes or no.
If a two liner then it may include &quot;Keys&quot; or &quot;Poly&quot; and &quot;Channel&quot;.
This will show whether the device will respond to Polyphonic after touch or channel after touch or neither.

Pitch Bend
Again &quot;O&quot; for implemented, &quot;X&quot; for not implemented.
(Many stage pianos will have no pitch bend capability.)
It may also, in the notes section, state whether it will respond to the full 14 bits, or not, as usually encoded by the pitch bend wheel.

Control Change
This is likely to be the largest section of the chart.
It will list all those controllers, starting from CC#0, Bank Select MSB, which the device is capable of sending, and those that it will respond to using &quot;O&quot; or &quot;X&quot; respectively.
You will, almost certainly, get some further explanation of functionality in the remarks column, or in more detail elsewhere in the documentation.

Of course you will need to know what all the various controller numbers do. Lots of the official technical specifications can be found at the [www.midi.org/techspecs/ MMA], with the table of messages and control change [www.midi.org/techspecs/midimessages.php message numbers]

Program Change
Again &quot;O&quot; or &quot;X&quot; in the Transmitted or Recognised column to indicate whether or not the feature is implemented. In addition a range of numbers is shown, typically 0-127, to show what is available.
True # (number): &quot;The range of the program change numbers which correspond to the actual number of patches selected.&quot;

System Exclusive
Used to indicate whether or not the device can send or recognise System Exclusive messages. A short description is often given in the Remarks field followed by a detailed explanation elsewhere in the documentation.

System Common - These include the following:
&lt;pre&gt;
MIDI Time Code Quarter Frame messages (device synchronisation).
Song Position Pointer
Song Select
Tune Request
&lt;/pre&gt;
The section will indicate whether or not the device can send or respond to any of these messages.

System Real Time
These include the following:
&lt;pre&gt;
Timing Clock - often just written as &quot;Clock&quot;
Start
Stop
Continue
&lt;/pre&gt;
These three are usually just referred to as &quot;Commands&quot; and listed.
Again the section will indicate which, if any, of these messages the device can send or respond to.
&lt;pre&gt;
Aux. Messages
Again &quot;O&quot; or &quot;X&quot; for implemented or not.
Aux. = Auxiliary.
Active Sense = Active Sensing.
&lt;/pre&gt;
Often with an explanation of the action of the device.

Notes
The &quot;Notes&quot; section can contain any additional comments to clarify the particular implementation.

Some of the explanations have been drawn directly from the MMA MIDI 1.0 Detailed Specification.
And the detailed explanation of some of the functions will be found there, or in the General MIDI System Level 1 or General MIDI System Level 2 documents also published by the MMA.


 OFFICIAL MIDI SPECIFICATIONS

SUMMARY OF MIDI MESSAGES
Table 1 - Summary of MIDI Messages

The following table lists the major MIDI messages in numerical (binary) order (adapted from &quot;MIDI by the Numbers&quot; by D. Valenti, Electronic Musician 2/88, and updated by the MIDI Manufacturers Association.). This table is intended as an overview of MIDI, and is by no means complete.

WARNING! Details about implementing these messages can dramatically impact compatibility with other products. We strongly recommend consulting the official MIDI Specifications for additional information.

MIDI 1.0 Specification

Message Summary Channel Voice Messages [nnnn = 0-15 (MIDI Channel Number 1-16)]

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1000nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note Off event. 
This message is sent when a note is released (ended). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1001nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note On event. 
This message is sent when a note is depressed (start). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1010nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Polyphonic Key Pressure (Aftertouch). 
This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. (kkkkkkk) is the key (note) number. (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Control Change. 
This message is sent when a controller value changes. Controllers include devices such as pedals and levers. Controller numbers 120-127 are reserved as &quot;Channel Mode Messages&quot; (below). (ccccccc) is the controller number (0-119). (vvvvvvv) is the controller value (0-127).
|-
|&lt;!--Status--&gt;1100nnnn || &lt;!--Data--&gt;0ppppppp || &lt;!--Description--&gt;Program Change. This message sent when the patch number changes. (ppppppp) is the new program number.
|-
|&lt;!--Status--&gt;1101nnnn || &lt;!--Data--&gt;0vvvvvvv || &lt;!--Description--&gt;Channel Pressure (After-touch). This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. This message is different from polyphonic after-touch. Use this message to send the single greatest pressure value (of all the current depressed keys). (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1110nnnn || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Pitch Bend Change. This message is sent to indicate a change in the pitch bender (wheel or lever, typically). The pitch bender is measured by a fourteen bit value. Center (no pitch change) is 2000H. Sensitivity is a function of the receiver, but may be set using RPN 0. (lllllll) are the least significant 7 bits. (mmmmmmm) are the most significant 7 bits.
|}

Channel Mode Messages (See also Control Change, above)

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Channel Mode Messages. 
This the same code as the Control Change (above), but implements Mode control and special message by using reserved controller numbers 120-127. The commands are:
*All Sound Off. When All Sound Off is received all oscillators will turn off, and their volume envelopes are set to zero as soon as possible c = 120, v = 0: All Sound Off
*Reset All Controllers. When Reset All Controllers is received, all controller values are reset to their default values. (See specific Recommended Practices for defaults) c = 121, v = x: Value must only be zero unless otherwise allowed in a specific Recommended Practice.
*Local Control. When Local Control is Off, all devices on a given channel will respond only to data received over MIDI. Played data, etc. will be ignored. Local Control On restores the functions of the normal controllers. 
c = 122, v = 0: Local Control Off
c = 122, v = 127: Local Control On
* All Notes Off. When an All Notes Off is received, all oscillators will turn off. 
c = 123, v = 0: All Notes Off (See text for description of actual mode commands.)
c = 124, v = 0: Omni Mode Off 
c = 125, v = 0: Omni Mode On 
c = 126, v = M: Mono Mode On (Poly Off) where M is the number of channels (Omni Off) or 0 (Omni On) 
c = 127, v = 0: Poly Mode On (Mono Off) (Note: These four messages also cause All Notes Off)
|}

System Common Messages

System Messages (0xF0)

The final status nybble is a “catch all” for data that doesn’t fit the other statuses. They all use the most significant nybble (4bits) of 0xF, with the least significant nybble indicating the specific category.

The messages are denoted when the MSB of the second nybble is 1. When that bit is a 0, the messages fall into two other subcategories.

System Common

If the MSB of the second second nybble (4 bits) is not set, this indicates a System Common message. Most of these are messages that include some additional data bytes.

System Common Messages
Type Status Byte   Number of Data Bytes      Usage 
&lt;pre&gt;
Time Code Quarter Frame	0xF1	1	Indicates timing using absolute time code, primarily for synthronization with video playback systems. A single location requires eight messages to send the location in an encoded hours:minutes:seconds:frames format*.
Song Position	0xF2	2	Instructs a sequencer to jump to a new position in the song. The data bytes form a 14-bit value that expresses the location as the number of sixteenth notes from the start of the song.
Song Select	0xF3	1	Instructs a sequencer to select a new song. The data byte indicates the song.
Undefined	0xF4	0	
Undefined	0xF5	0	
Tune Request	0xF6	0	Requests that the receiver retunes itself**.
&lt;/pre&gt;
*MIDI Time Code (MTC) is significantly complex. Please see the MIDI Specification
**While modern digital instruments are good at staying in tune, older analog synthesizers were prone to tuning drift. Some analog synthesizers had an automatic tuning operation that could be initiated with this command.


System Exclusive

If you’ve been keeping track, you’ll notice there are two status bytes not yet defined: 0xf0 and 0xf7. These are used by the System Exclusive message, often abbreviated at SysEx. SysEx provides a path to send arbitrary data over a MIDI connection. There is a group of predefined messages for complex data, like fine grained control of MIDI Time code machinery. SysEx is also used to send manufacturer defined data, such as patches, or even firmware updates.

System Exclusive messages are longer than other MIDI messages, and can be any length. The messages are of the following format:

0xF0, 0xID, 0xdd, ...... 0xF7
The message is bookended with distinct bytes.

It opens with the Start Of Exclusive (SOX) data byte, 0xF0.
The next one to three bytes after the start are an identifier.
Values from 0x01 to 0x7C are one-byte vendor IDs, assigned to manufacturers who were involved with MIDI at the beginning.
If the ID is 0x00, it’s a three-byte vendor ID - the next two bytes of the message are the value.
&lt;pre&gt;
ID 0x7D is a placeholder for non-commercial entities.
ID 0x7E indicates a predefined Non-realtime SysEx message.
ID 0x7F indicates a predefined Realtime SysEx message.
&lt;/pre&gt;
After the ID is the data payload, sent as a stream of bytes.
The transfer concludes with the End of Exclusive (EOX) byte, 0xF7.
The payload data must follow the guidelines for MIDI data bytes – the MSB must not be set, so only 7 bits per byte are actually usable. If the MSB is set, it falls into three possible scenarios.

An End of Exclusive byte marks the ordinary termination of the SysEx transfer.
System Real Time messages may occur within the transfer without interrupting it. The recipient should handle them independently of the SysEx transfer.
Other status bytes implicitly terminate the SysEx transfer and signal the start of new messages.
 Some inexpensive USB-to-MIDI interfaces aren’t capable of handling messages longer than four bytes.

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11110000 || &lt;!--Data--&gt;0iiiiiii [0iiiiiii 0iiiiiii]  0ddddddd  --- --- 0ddddddd 11110111 || &lt;!--Description--&gt;System Exclusive. 
This message type allows manufacturers to create their own messages (such as bulk dumps, patch parameters, and other non-spec data) and provides a mechanism for creating additional MIDI Specification messages. The Manufacturer's ID code (assigned by MMA or AMEI) is either 1 byte (0iiiiiii) or 3 bytes (0iiiiiii 0iiiiiii 0iiiiiii). Two of the 1 Byte IDs are reserved for extensions called Universal Exclusive Messages, which are not manufacturer-specific. If a device recognizes the ID code as its own (or as a supported Universal message) it will listen to the rest of the message (0ddddddd). Otherwise, the message will be ignored. (Note: Only Real-Time messages may be interleaved with a System Exclusive.)
|-
|&lt;!--Status--&gt;11110001 || &lt;!--Data--&gt;0nnndddd || &lt;!--Description--&gt;MIDI Time Code Quarter Frame.
nnn = Message Type
dddd = Values
|-
|&lt;!--Status--&gt;11110010 || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Song Position Pointer. 
This is an internal 14 bit register that holds the number of MIDI beats (1 beat= six MIDI clocks) since the start of the song. l is the LSB, m the MSB.
|-
|&lt;!--Status--&gt;11110011 || &lt;!--Data--&gt;0sssssss || &lt;!--Description--&gt;Song Select. 
The Song Select specifies which sequence or song is to be played.
|-
|&lt;!--Status--&gt;11110100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Tune Request. Upon receiving a Tune Request, all analog synthesizers should tune their oscillators.
|-
|&lt;!--Status--&gt;11110111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;End of Exclusive. Used to terminate a System Exclusive dump. 
|}


System Real-Time Messages

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11111000 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Timing Clock. Sent 24 times per quarter note when synchronization is required.
|-
|&lt;!--Status--&gt;11111001 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111010 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Start. Start the current sequence playing. (This message will be followed with Timing Clocks).
|-
|&lt;!--Status--&gt;11111011 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Continue. Continue at the point the sequence was Stopped.
|-
|&lt;!--Status--&gt;11111100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Stop. Stop the current sequence.
|-
|&lt;!--Status--&gt;11111101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Active Sensing. This message is intended to be sent repeatedly to tell the receiver that a connection is alive. Use of this message is optional. When initially received, the receiver will expect to receive another Active Sensing message each 300ms (max), and if it does not then it will assume that the connection has been terminated. At termination, the receiver will turn off all voices and return to normal (non- active sensing) operation. 
|-
|&lt;!--Status--&gt;11111111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Reset. Reset all receivers in the system to power-up status. This should be used sparingly, preferably under manual control. In particular, it should not be sent on power-up.
|}


Advanced Messages

Polyphonic Pressure (0xA0) and Channel Pressure (0xD0)

Some MIDI controllers include a feature known as Aftertouch. While a key is being held down, the player can press harder on the key. The controller measures this, and converts it into MIDI messages.

Aftertouch comes in two flavors, with two different status messages.

The first flavor is polyphonic aftertouch, where every key on the controller is capable of sending its own independent pressure information. The messages are of the following format:
&lt;pre&gt;
0xnc, 0xkk, 0xpp
n is the status (0xA)
c is the channel nybble
kk is the key number (0 to 127)
pp is the pressure value (0 to 127)
&lt;/pre&gt;
Polyphonic aftertouch is an uncommon feature, usually found on premium quality instruments, because every key requires a separate pressure sensor, plus the circuitry to read them all.

Much more commonly found is channel aftertouch. Instead of needing a discrete sensor per key, it uses a single, larger sensor to measure pressure on all of the keys as a group. The messages omit the key number, leaving a two-byte format
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xD)
c is the channel number
pp is the pressure value (0 to 127)
&lt;/pre&gt;

Pitch Bend (0xE0)

Many keyboards have a wheel or lever towards the left of the keys for pitch bend control. This control is usually spring-loaded, so it snaps back to the center of its range when released. This allows for both upward and downward bends.

Pitch Bend Wheel

The wheel sends pitch bend messages, of the format
&lt;pre&gt;
0xnc, 0xLL, 0xMM
n is the status (0xE)
c is the channel number
LL is the 7 least-significant bits of the value
MM is the 7 most-significant bits of the value
&lt;/pre&gt;
You’ll notice that the bender data is actually 14 bits long, transmitted as two 7-bit data bytes. This means that the recipient needs to reassemble those bytes using binary manipulation. 14 bits results in an overall range of 214, or 0 to 16,383. Because it defaults to the center of the range, the default value for the bender is halfway through that range, at 8192 (0x2000).

Control Change (0xB0)

In addition to pitch bend, MIDI has provisions for a wider range of expressive controls, sometimes known as continuous controllers, often abbreviated CC. These are transmitted by the remaining knobs and sliders on the keyboard controller shown below.


Continuous Controllers

These controls send the following message format:
&lt;pre&gt;
0xnc, 0xcc, 0xvv
n is the status (0xB)
c is the MIDI channel
cc is the controller number (0-127)
vv is the controller value (0-127)
&lt;/pre&gt;

Typically, the wheel next to the bender sends controller number one, assigned to modulation (or vibrato) depth. It is implemented by most instruments.

The remaining controller number assignments are another point of confusion. The MIDI specification was revised in version 2.0 to assign uses for many of the controllers. However, this implementation is not universal, and there are ranges of unassigned controllers.

On many modern MIDI devices, the controllers are assignable. On the controller keyboard shown in the photos, the various controls can be configured to transmit different controller numbers. Controller numbers can be mapped to particular parameters. Virtual synthesizers frequently allow the user to assign CCs to the on-screen controls. This is very flexible, but it might require configuration on both ends of the link and completely bypasses the assignments in the standard.


Program Change (0xC0)

Most synthesizers have patch storage memory, and can be told to change patches using the following command:
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xc)
c is the channel
pp is the patch number (0-127)
&lt;/pre&gt;
This allows for 128 sounds to be selected, but modern instruments contain many more than 128 patches. Controller #0 is used as an additional layer of addressing, interpreted as a “bank select” command. Selecting a sound on such an instrument might involve two messages: a bank select controller message, then a program change.

Audio &amp; Midi are not synchronized, what I can do ?
Buy a commercial software package but there is a nasty trick to synchronize both. It's a bit hardcore but works for me:

 Simply put one line down to all midi notes on your pattern (use Insert key)
 and go to 'Misc. Setup', adjust the latency and just search a value
 that will make sound sync both audio/midi.

The stock Sin/Saw/Pulse and Rnd waveforms are too simple/common, is there a way to use something more complex/rich ?
You have to ability to redirect the waveforms of the instruments through the synth pipe by selecting the &quot;wav&quot; option for the oscillator you're using for this synth instrument, samples can be used as wavetables to replace the stock signals.


Sound banks like soundfont (sf2) or Kontakt2 are not supported at the moment


====DAW Audio Evolution 4====

Audio Evolution 4 gives you unsurpassed power for digital audio recording and editing on the Amiga. The latest release focusses on time-saving non-linear and non-destructive editing, as seen on other platforms. Besides editing, Audio Evolution 4 offers a wide range of realtime effects, including compression, noise gate, delays, reverb, chorus and 3-band EQ.

Whether you put them as inserts on a channel or use them as auxillaries, the effect parameters are realtime adjustable and can be fully automated. Together with all other mixing parameters, they can even be controlled remotely, using more ergonomic MIDI hardware.

Non-linear editing on the time line, including cut, copy, paste, move, split, trim and crossfade actions

The number of tracks per project(s) is unlimited .... AHI limits you to recording only two at a time. i.e. not on 8 track sound cards like the Juli@ or Phase 88.

sample file import is limited to 16bit AIFF (not AIFC, important distinction as some files from other sources can be AIFC with aiff file extention). and 16bit WAV (pcm only)


Most apps use the Music Unit only but a few apps also use Unit (0-3) instead or as well. 
* Set up AHI prefs so that microphone is available. (Input option near the bottom)


stereo++ allows the audio piece to be placed anywhere and the left-right adjusted to sound positionally right

hifi best for music playback if driver supports this option


Load 16bit .aif .aiff only sample(s) to use not AIFC which can have the same ending. AIFF stands for Audio Interchange File Format 

 sox recital.wav recital.aiff

 sox recital.wav −b 16 recital.aiff channels 1 rate 16k fade 3 norm
 sox input.wav        output.aiff bass −b 16 rate 48k

performs the same format translation, but also applies four effects (down-mix to one channel, sample rate change, fade-in, nomalize), and stores the result at a bit-depth of 16.

 rec −c 2 radio.aiff trim 0 30:00

records half an hour of stereo audio 

 play existing-file.wav


24bit PCM WAV or AIFF do not work 

*No stream format handling. So no way to pass on an AC3 encoded stream unmodified to the digital outputs through AHI.
*No master volume handling. Each application has to set its own volume. So each driver implements its own custom driver-mixer interface for handling master volumes, mute and preamps.
*Only one output stream. So all input gets mixed into one output.
*No automatic handling of output direction based on connected cables.
*No monitor input selection. Only monitor volume control. 


select the correct input (Don't mistake enabled sound for the correct input.)
The monitor will feedback audio to the lineout and hp out no matter if you have selected the correct input to the ADC. The monitor will provide sound for any valid input. This will result in free mixing when recording from the monitor input instead of mic/line because the monitor itself will provide the hardware mixing for you. Be aware that MIC inputs will give two channel mono. Only Linein will give real stereo.

Now for the not working part. Attempt to record from linein in the AE4 record window, the right channel is noise and the left channel is distorted. Even with the recommended HIFI 16bit Stereo++ mode at 48kHz.


Channels

Monitor

Gain

Inout

Output

Advanced settings - Debugging via serial port


* Options -&gt; Soundcard In/Out
* Options -&gt; SampleRate
* Options -&gt; Preferences

F6 for Sample File List

Setting a grid is easy as is measuring the BPM by marking a section of the sample. Is your kick drum track &quot;not in time&quot; ? If so, you're stumped in AE4 as it has no fancy variable time signatures and definitely no 'track this dodgy rhythm' function like software of the nature of Logic has. So if your drum beat is freeform you will need to work in freeform mode. (Real music is free form anyway).

If the drum *is* accurate and you are just having trouble measuring the time, I usually measure over a range of bars and set the number of beats in range to say 16 as this is more accurate, Then you will need to shift the drum track to match your grid *before* applying the grid. (probably an iterative process as when the grid is active samples snap to it, and when inactive you cannot see it).

AE4 does have ARexx but the functions are more for adding samples at set offsets and starting playback / recording.


These are the usual features found in DAWs...

* Recording digital audio, midi sequencer and mixer 
* virtual VST instruments and plug-ins 
* automation, group channels, MIDI channels, FX sends and returns, audio and MIDI editors and music notation editor


* different track views 
* mixer and track layout (but not the same as below) 
* traditional two windows (track and mixer)


Mixing - mixdown

Could not figure out how to select what part I wanted to send to the aux, set it to echo and return. Pretty much the whole echo effect. Or any effect.

Take look at page17 of the manual.

When you open the EQ / Aux send popup window you will see 4 sends. Now from the menu choose the windows menu.

Menus-&gt;Windows-&gt; Aux Returns Window

or press F5

You will see a small window with 4 volume controls and an effects button for each. Click a button and add an effects to that aux channel, then set it up as desired (note the reverb effect has a special AUX setting that improves its use with the aux channel, not compulsory but highly useful). You set the amount of 'return' on the main mix in the Aux Return window, and the amount sent from each main mixer channel in the popup for that channel. Again the aux sends are &quot;prefade&quot; so the volume faders on each channel do not affect them.


Tracking


Effects - fade in

To add some echoes to some vocals, tried to add an effect on a track but did not come out. This is made more complicated as I wanted to mute a vocal but then make it echo at the muting point. Want to have one word of a vocal heard and then echoed off. But when the track is mute the echo is cancelled out.

To correctly understand what is happening here you need to study the figure at the bottom of page 15 on the manual. You will see from that that the effects are applied 'prefade' So the automation you applied will naturally mute the entire signal.

There would be a number of ways to achieve the goal,

You have three real time effects slots, one for smoothing like so

Sample -&gt; Amplify -&gt; Delay

Then automate the gain of the amplify block so that it effectively mutes the sample just before the delay at the appropriate moment, the echo effect should then be heard.

Getting the effects in the right order will require experimentation as they can only be added top down and it's not obvious which order they are applied to the signal, but there only two possibilities, so it wont take long to find out.

Using MUTE can cause clicks to the Amplify can be used to mute more smoothly so that's a secondary advantage.

Signal Processing -


Overdub

[[#top|...to the top]]

===Office===

====Spreadsheet Leu====

Support for some xlsx, and ods functions 


====Spreadsheet Ignition====

; Needs ABIv1 to be completed before more can be done

File formats supported 
* ascii #?.txt and #?.csv (single sheets with data only). 
* igs and TurboCalc(WIP) #?.tc for all sheets with data, formats and formulas.

There is '''no''' support for xls, xlsx, ods or uos ([http://en.wikipedia.org/wiki/Uniform_Office_Format Uniform Unified Office Format]) at the moment.

* Always use Esc key after editing Spreadsheet cells.
* copy/paste seems to copy the first instance only so go to Edit -&gt; Clipboard to manage the list of remembered actions. 
* Right mouse click on row (1 or 2 or 3) or column header (a or b or c)  to access optimal height or width of the row or column respectively 
* Edit -&gt; Insert -&gt; Row  seems to clear the spreadsheet or clears the rows after the inserted row until undo restores as it should be...

Change Sheet name by  Object -&gt; Sheet -&gt; Properties

Click in the cell which will contain the result, and click '''down arrow button''' to the right of the formula box at the bottom of the spreadsheet and choose the function required from the list provided. Then click on the start cell and click on the bottom right corner, a '''very''' small blob, which allows stretching a bounding box (thick grey outlines) across many cells This grey bounding box can be used to '''copy a formula''' to other cells.

Object -&gt; Cell -&gt; Properties to change cell format - Currency only covers DM and not $, Euro, Renminbi, Yen or Pound etc. 
Shift key and arrow keys selects a range of cells, so that '''formatting can be done to all highlighted cells'''. 
View -&gt; Overview then select ALL with one click (in empty cell in the top left hand corner of the sheet).

Default mode is relative cell referencing e.g. a1+a2 but absolute e.g. $a$1+$a$2 can be entered.

* #sheet-name to '''absolute''' reference another sheet-name cell unless reference() function used.

;Graphs

use shift key and arrow keys to select a bunch of cells to be graph'ed making sure that x axes represents and y axes represents

* value() - 0 value, 1 percent, 2 date, 3 time, 4 unit ...


;Dates 
* Excel starts a running count from the 1st Jan 1900 and Ignition starts from 1st Jan 1AD '''(maybe this needs to change)'''
Set formatting Object -&gt; Cell -&gt; Properties and put date in days


;Time 
Set formatting Object -&gt; Cell -&gt; Properties and put time in seconds taken


;Database (to be done by someone else)

type - standard, reference (bezug), search criterion (suchkriterium), 
* select a bunch of cells and Object -&gt; Database -&gt; Define to set Datenbank (database) and Felder (fields not sure how?) 
* Neu (new) or loschen (delete) to add/remove database headings e.g. Personal, Start Date, Finish Date (one per row?)
* Object -&gt; Database -&gt; Index to add fields (felder) like Surname, First Name, Employee ID, etc. to ?

Filtering done with dbfilter(), dbproduct() and dbposition().

Activities with dbsum(), dbaverage(), dbmin() and dbmax().

Table sorting -


;Scripts (Arexx)

;Excel(TM) to Ignition - commas ''',''' replaced by semi-colons ''';''' to separate values within functions 
*SUM(), 
*AVERAGE(), MAX(), MIN(), INT(), PRODUCT(), MEDIAN(), VAR() becomes Variance(), Percentile(),
*IF(), AND, OR, NOT 
*LEFT(), RIGHT(), MID() becomes MIDDLE(), LEN() becomes LENGTH(), 
*LOWER() becomes LOWERCASE(), UPPER() becomes UPPERCASE(),
* DATE(yyyy,mm,dd) becomes COMPUTEDATE(dd;mm;yyyy), 
*TODAY(), DAY(),WEEK(), MONTH(),=YEAR(TODAY()), 
*EOMONTH() becomes MONTHLENGTH(), 
*NOW() should be date and time becomes time only, SECOND(), MINUTE(), HOUR(),
*DBSUM() becomes DSUM(),


;Missing and possibly useful features/functions needed for ignition to have better support of Excel files 
There is no Merge and Join Text over many cells, no protect and/or freeze row or columns or books but can LOCK sheets, no define bunch of cells as a name, Macros (Arexx?), conditional formatting, no Solver, no Goal Seek, no Format Painter, no AutoFill, no AutoSum function button, no pivot tables, (30 argument limit applies to Excel)

*HLOOKUP(), VLOOKUP(), [http://production-scheduling.com/excel-index-function-most-useful/ INDEX(), MATCH()], CHOOSE(), TEXT(), 
*TRIM(), FIND(), SUBSTITUTE(), CONCATENATE() or &amp;, PROPER(), REPT(), 
*[https://acingexcel.com/excel-sumproduct-function/ SUMPRODUCT()], ROUND(), ROUNDUP(), *ROUNDDOWN(), COUNT(), COUNTA(), SUMIF(), COUNTIF(), COUNTBLANK(), TRUNC(), 
*PMT(), PV(), FV(), POWER(), SQRT(), MODE(), TRUE, FALSE, 
*MODE(), LARGE(), SMALL(), RANK(), STDEV(), 
*DCOUNT(), DCOUNTA(), WEEKDAY(),


;Excel Keyboard [http://dmcritchie.mvps.org/excel/shortx2k.htm shortcuts needed to aid usability in Ignition] 
&lt;pre&gt;
Ctrl Z - Undo

Ctrl D - Fill Down
Ctrl R - Fill right

Ctrl F - Find
Ctrl H - Replace

Ctrl 1 - Formatting of Cells
CTRL SHIFT ~ Apply General Formatting ie a number 
Ctrl ; - Todays Date 

F2 - Edit cell
F4 - toggle cell absolute / relative cell references

&lt;/pre&gt;


====Document Scanning - Scandal====

Scanner usually needs to be connected via a USB port and not via a hub or extension lead.

Check in Trident Prefs -&gt; Devices that the USB Scanner is not bound to anything (e.g. Bindings None)
If not found then reboot the computer and recheck.

Start Scandal, choose Settings from Menu strip at top of screen and in Scanner Driver choose the ?#.device of the scanner (e.g. epson2.device).

The next two boxes - leave empty as they are for morphos SCSI use only
 or put ata.device (use the selection option in bigger box below) and Unit as 0 this is needed for gt68xx

* gt68xx - no editing needed in s/gt68xx.conf but needs a firmware file that corresponds to the scanner [http://www.meier-geinitz.de/sane/gt68xx-backend/ gt68xx firmwares] in sys:s/gt68xx.
* epson2 - Need to edit the file epson2.conf in sys/s that corresponds to the scanner being used

'''Save''' the settings but do not press the Use button (aros freezes)

Back to the Picture Scan window and the right-hand sections.

Click on the '''Information''' tab and press Connect button and the scanner should now be detected.

Go next to the '''Scanner''' tab next to Information Tab should have Color, Black and White, etc. and dpi settings now. Selecting an option Color, B/W etc. can cause dpi settings corruption (especially if the settings are in one line) so set '''dpi first'''. Make sure if Preview is set or not.

In the '''Scan''' Tab, press Scan and the scanner will do its duty. 
Be aware that nothing is saved to disk yet.

In the Save tab, change format JPEG, PNG or IFF DEEP. Tick incremental and base filename if necessary and then click the Save button. The image will now be saved to permanent storage.


The driver ignores a device if it is already bond to another USB class, rejects it from being usable. However, open Trident prefs, select your device and use the right mouse button to open. Select &quot;NONE&quot; to prevent poseidon from touching the device. Now save settings. It should always work now.

[[#top|...to the top]]

===Emulators===

==== Amiberry ====


==== Amiga Emu - Janus UAE ====

With Amibridge, AROS attempts to make the UAE emulator seem embedded within but it still is acting as an app 

There is no dynarec m68k for each hardware that Aros supports or direct patching of motorola calls to AROS hardware accelerated ones unless the emulator has that included 

Try starting Janus with a priority of -1 like this little script:
&lt;pre&gt;
cd sys:system/AmiBridge/emulator
changetaskpri -1
run janus-uae -f my_uaerc.config &gt;nil:
cd sys:prefs
endcli
&lt;/pre&gt;
This stops Janus hogging all the CPU time.


===Miscellaneous===

====Screensaver Blanker====

Most blankers on the amiga (i.e. aros) run as commodities (they are in the tools/commodities drawer). Double click on blanker.

Control is with an app called Exchange, which you need to run first (double click on app) or  run QUIET sys:tools/commodities/Exchange &gt;NIL: but subsequently can use (Cntrl Alt h).

Icon tool types (may be broken) or command line options 
&lt;pre&gt;
seconds=number 
&lt;/pre&gt;

Once the timing is right then add the following to s:icaros-sequence or s:user-startup

e.g. for 5 minutes

 run QUIET sys:tools/commodities/Blanker seconds=300 &gt;NIL:


*[http://archives.aros-exec.org/index.php?function=showfile&amp;file=graphics/screenblanker/gblanker.i386-aros.zip Garshneblanker] can make Aros unstable or slow. Certain blankers crashes in Icaros 2.0.x like Dragon, Executor.


*[ Acuario AROS version], the aquarium screen saver.

Startup: extras:acuariofv-aros/acuario

Kill: c:break name=extras:acuariofv-aros/acuario

Managed to start Acuario by the Executor blanker.

&lt;pre&gt;
cx_priority=
cx_popkey=    ie CX_POPKEY=&quot;Shift F1&quot; 
cx_popup=Yes or No

&lt;/pre&gt;


&lt;pre&gt;
 Qualifier String    Input Event Class
   ----------------    -----------------
    &quot;lshift&quot;           IEQUALIFIER_LSHIFT
    &quot;rshift&quot;           IEQUALIFIER_RSHIFT
    &quot;capslock&quot;         IEQUALIFIER_CAPSLOCK
    &quot;control&quot;          IEQUALIFIER_CONTROL
    &quot;lalt&quot;             IEQUALIFIER_LALT
    &quot;ralt&quot;             IEQUALIFIER_RALT
    &quot;lcommand&quot;         IEQUALIFIER_LCOMMAND
    &quot;rcommand&quot;         IEQUALIFIER_RCOMMAND
    &quot;numericpad&quot;       IEQUALIFIER_NUMERICPAD
    &quot;repeat&quot;           IEQUALIFIER_REPEAT
    &quot;midbutton&quot;        IEQUALIFIER_MIDBUTTON
    &quot;rbutton&quot;          IEQUALIFIER_RBUTTON
    &quot;leftbutton&quot;       IEQUALIFIER_LEFTBUTTON
    &quot;relativemouse&quot;    IEQUALIFIER_RELATIVEMOUSE
&lt;/pre&gt;


&lt;pre&gt;
    Synonym     Synonym
    String     Identifier
    -------    ----------
    &quot;shift&quot;    IXSYM_SHIFT    /* look for either shift key */
    &quot;caps&quot;     IXSYM_CAPS     /* look for either shift key or capslock */
    &quot;alt&quot;      IXSYM_ALT      /* look for either alt key */

Highmap is one of the following strings:
    &quot;space&quot;, &quot;backspace&quot;, &quot;tab&quot;, &quot;enter&quot;, &quot;return&quot;, &quot;esc&quot;, &quot;del&quot;,
    &quot;up&quot;, &quot;down&quot;, &quot;right&quot;, &quot;left&quot;, &quot;f1&quot;, &quot;f2&quot;, &quot;f3&quot;, &quot;f4&quot;, &quot;f5&quot;,
    &quot;f6&quot;, &quot;f7&quot;, &quot;f8&quot;, &quot;f9&quot;, &quot;f10&quot;, &quot;help&quot;.


&lt;/pre&gt;


[[#top|...to the top]]

==== World Construction Set WCS (Version 2.031) ====

WCS is a fractal landscape software such as Scenery Animator, Vista Pro and Panorama. Open sourced February 2022, World Construction Set [https://3dnature.com/downloads/legacy-software/ legally and for free] and [https://github.com/AlphaPixel/3DNature c source]. 

Announced August 1994 this version dates from April 1996 developed by Gary R. Huber and Chris &quot;Xenon&quot; Hanson&quot; from Questar 

&lt;pre&gt;
Assign &quot;WCSProjects:&quot; &quot;Volume:Dir/Dir/WCSProjects&quot; 
Assign &quot;WCSFrames:&quot;   &quot;Volume:Dir/Dir/WCSFrames&quot; 
&lt;/pre&gt;

&lt;pre&gt;
Load projects .proj by accessing pull down menu Project -&gt; Open then click on CanyonSunset.proj
OK to changing .par file and enlarge Status Log window to show what is happening 
Render by pull down menu Modules -&gt; Render with End equal 1 not 300 then click bottom middle button Render 
&lt;/pre&gt;

[https://www.youtube.com/watch?v=CxQDmf1ZWG0 Youtube walkthrough of above], [], [], 

Also try working with the already built file ColoDemo - Then open with the drop-down menu: Project/Open, then WCSProject:ColoDemo.proj
Which allows you to use altimetric DEM files already included and Loading scene parameters from ColoDemo.par
Once this is done, save everything with a new name to start working exclusively on your project. 
Then drop-down menu and select Save As (&quot;NewName&quot;.proj name), then drop-down menu to open parameter and select Save All ( .par name)


After launching the software, there is a the Module Control Panel composed of five icons. 
It is a dock type shortcut of the first few functions of the drop-down menu 

*Database   - Load (#?.proj), Append, Create, Edit, Save, Dir List (of WCSProject drawer), 
*Data Ops   - Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats  
*Map View   - Database file Loader leading to Map View Control with option to the Database Editor 
*Parameters - Editor for Motion, Color, Ecosystem, Clouds, Waves, management of altimeter files DEM, sclock settings etc 
*Render     - rendering terrain 

These are more in the pull down menu but not in the dock 
*Motion Editor
*Color Editor
*Ecosys Editor 


Simple minimal workflow 
*Load database (1st icon - 1st)
*Set parameters and save .par file (4th icon)
*Render scene (5th icon) 

[https://www.youtube.com/watch?v=ZbTwwR2qcc4 Youtube], [], 

&lt;pre&gt;
.proj new project name which creates a drawer of additional files 

.binary array, ascii array .xyz , z buffer, DTED .dt0, vista 1990s dem, iff  conversion 
.Obj with .elev, .frd with .hdr maps, - digital elevation model (DEM) is a 3D representation of elevation data in various formats 
USGS 7.5MinDEM, 

.par 


&lt;/pre&gt;


Since for the time being no project is loaded, a query window indicates a procedural error when clicking on the rendering icon (right end of the bar). The menu is quite traditional; it varies according to the activity of the windows. To display any altimetric file in the &quot;Mapview&quot; (third icon of the panel), There are three possibilities:

* Loading of a demonstration project.
* The import of a DEM file, followed by texturing and packaging from the &quot;Database-Editor&quot; and the &quot;Color-Editor&quot;.
* The creation of an altimetric file in WCS format, then texturing.


The altimeter file editing (display in the menu) is only made possible if the &quot;Mapview&quot; window is active.

The software is made up of many windows and won't be able to describe them all. Know that &quot;Color-Editor&quot; and the &quot;Data-Editor&quot; comprise sufficient functions for obtaining an almost real rendering quality. You have the possibility of inserting vector objects in the &quot;Data-Editor&quot; (creation of roads, railways, etc.) 


The Map View (MapView) window

*Database - Objects and Topos
*View     - Align, Center, Zoom, Pan, Move 
*Draw     - Maps and distance 
*Object   - Find, highlight, add points, conform topo, duplicate 
*Motion   - Camera, Focus, path, elevation 
*Windows  - DEM designer, Cloud (.cld) and wave (.wve) editor, 


You will notice that by selecting this window and simply moving the pointer to various points on the map you will see latitude and longitude values ​​change, along with the height.
Drop-down menu and Modules, then select MapView and change the width of the window with the map to arrange it in the best way on the screen. With the Auto button the center. Window that then displays the contents of my DEM file, in this case the Grand Canyon. MapView allows you to observe the shape of the landscape from above
 

ZOOM button

Press the Zoom button and then with the pointer position on a point on the map, press the left mouse button and then move to the opposite corner to circumscribe the chosen area and press the left mouse button again, then we will see the enlarged area selected on the map.
Would add that there is a box next to the Zoom button that allows the direct insertion of a value which, the larger it is, the smaller the magnification and the smaller the value, the stronger the magnification. At each numerical change you will need to press the DRAW button to update the view.

PAN button

Under Zoom you will find the PAN button which allows you to move the map at will in all directions by the amount you want. This is done by drawing a line in one direction, then press PAN and point to an area on the map with the pointer and press the left mouse button. At this point, leave it and move the pointer in one direction by drawing a line and press the left mouse button again to trigger the movement of the map on the screen (origin and end points). Do some experiments and then use the Auto button immediately below to recenter everything.
There are parameters such as TOPO, VEC to be left checked and immediately below one that allows different views of the map with the Style command (Single, Multi, Surface, Emboss, Slope, Contour), each with its own particularities to highlight different details.

Now you have the first basics to manage your project visually on the map. Close the MapView window and go further...


Let's start working on ECOSYSTEMS
If we select Emboss from the MapView Style command we will have a clear idea of ​​how the landscape appears, realizing that it is a predominantly desert region of our planet. Therefore we will begin to act on any vegetation present and the appearance of the landscape.
With WCS we will begin to break down the elements of the landscape by assigning defined characteristics. It will be necessary to determine the classes of the ecosystem (Class) with parameters of Elevation Line (maximum altitude), Relative Elevation (arrangement on basins or convexities with respectively positive or negative parameters), Min Slope and Max Slope (slope). WCS offers the possibility of making ecosystems coexist on the same terrain with the UnderEco function, by setting a Density value.


Ecosys Ecosystem Editor

Let's open it from Modules, then Ecosys Editor. In the left pane you will find the list of ecosystems referring to the files present in our project. It will be necessary to clean up that box to leave only the Water and Snow landscapes and a few other predefined ones. We can do this by selecting the items and pressing the Remove button (be careful not for all elements the button is activated, therefore they cannot all be eliminated).
Once this is done we can start adding new ecosystems. Scroll through the various Unused and as soon as the Name item at the top is activated allowing you to write, type the name of your ecosystem, adding the necessary parameters.
&lt;pre&gt;
Ecosystem1: Name: RockBase Class: Rock Density: 80 MinSlope: 15 UnderEco: Terrain
Ecosystem2: Name: RockIncl Clss: Rock Density: 80 MinSlope: 30 UnderEco: Terrain
Ecosystem3: Name: Grass Class Low Veg Density: 50 Height: 1 Elev Line : 1500 Rel El Eff: 5
Max Slope: 10 – Min Slope: 0 UnderEco: Terrain
Ecosistema4: Name: Shrubs Class: Low Veg Density: 40 Height: 8 Elev Line: 3000
Rel El Eff: -2 Max Slope: 20 Min Slope : 5 UnderEco: Terrain
Ecosistema5: Name: Terrain Class: Ground Density: 100 UnderEco: Terrain
&lt;/pre&gt;

Now we need to identify an intermediate ecosystem that guarantees a smooth transition between all, therefore we select as Understory Ecosystem the one called Terrain in all ecosystems, except Snow and Water .
Now we need to 'emerge' the Colorado River in the Canyon and we can do this by raising the sea level to 900 (Sea Level) in the Ecosystem called Water.
Please note that the order of the ecosystem list gives priority to those that come after. So our list must have the following order: Water, Snow, Shrubs, RockIncl, RockBase, Terrain. It is possible to carry out all movements with the Swap button at the bottom. To put order you can also press Short List. Press Keep to confirm all the work done so far with Ecosystem Editor.
Remember every now and then to save both the Project 'Modules/Save' and 'Parameter/Save All'

EcoModels are made up of .etp .fgp .iff8 for each model 


Color Editor

Now it's time to define the colors of our scene and we can do this by going to Modules and then Color Editor. In the list we focus on our ecosystems, created first.
Let's go to the bottom of the list and select the first white space, assigning the name 'empty1', with a color we like and then we will find this element again in other environments... It could serve as an example for other situations!
So we move to 'grass' which already exists and assign the following colors: R 60 G 70 B50
&lt;pre&gt;
'shrubs': R 60 G 80 B 30
'RockIncl' R 110 G 65 B 60
'RockBase' R 110 G 80 B 80
' Terrain' R 150 G 30 B 30
&lt;pre&gt;
Now we can work on pre-existing colors
&lt;pre&gt;
'SunLight' R 150 G 130 B 130
'Haze and Fog' R 190 G 170 B 170
'Horizon' R 209 G 185 B 190
'Zenith' R 140 G 150 B 200
'Water' R 90 G 125 B 170
&lt;/pre&gt;

Ambient R 0 G 0 B 0

So don't forget to close Color Editor by pressing Keep.
Go once again to Ecosystem Editor and assign the corresponding color to each environment by selecting it using the Ecosystem Color button. Press it several times until the correct one appears. Then save the project and parameters again, as done previously.


Motion Editor

Now it's time to take care of the framing, so let's go to Modules and then to Motion Editor. An extremely feature-rich window will open. Following is the list of parameters regarding the Camera, position and other characteristics:
&lt;pre&gt;
-Camera Altitude: 7.0
-Camera Latitude: 36.075
-Camera Longitude: 112.133
-Focus Attitude: -2.0
-Focus Latitude: 36.275
-Focus Longitude: 112.386
-Camera : 512 → rendering window
-Camera Y: 384 → rendering window
-View Arc: 80 → View width in degrees
-Sun Longitude: 172
-Sun Latitude: -0.9
-Haze Start: 3.8
-Haze Range: 78, 5
&lt;/pre&gt;
As soon as the values ​​shown in the relevant sliders have been modified, we will be ready to open the CamView window to observe the wireframe preview. Let's not consider all the controls that will appear.
Well from the Motion Editor if you have selected Camera Altitude and open the CamView panel, you can change the height of the camera by holding down the right mouse button and moving the mouse up and down. To update the view, press the Terrain button in the adjacent window. As soon as you are convinced of the position, confirm again with Keep. You can carry out the same work with the other functions of the camera, such as Focus Altitude...
Let's now see the next positioning step on the Camera map, but let's leave the CamView preview window open while we go to Modules to open the window at the same time MapView. We will thus be able to take advantage of the view from the other together with a subjective one.


From the MapView window, select with the left mouse button and while it is pressed, move the Camera as desired. To update the subjective preview, always click on Terrain.
While with the same procedure you can intervene on the direction of the camera lens, by selecting the cross and with the left button pressed you can choose the desired view. So with the pressure of Terrain I update the Preview. Possibly can enlarge or reduce the Map View using the Zoom button, for greater precision.
Also write that the circle around the cameras indicates the beginning of the haze, there are two types (haze and fog) linked to the altitude. Would also add that the camera height is editable through the Motion Editor panel.


The sun

Let's see that changing the position of the sun from the Motion Editor. Press the SUN button at the bottom right and set the time and the date. Longitude and latitude are automatically obtained by the program. Always open the View Arc command from the Motion Editor panel, an item present in the Parameter List box.

Once again confirm everything with Keep and then save again.


Animation

The animation part is not left-back and also occupies a window. The settings possibilities are enormous. A time line with dragging functions (&quot;slide&quot;, &quot;drag&quot;...) comparable to that of LightWave completes this window. 


A small window is available for positioning the stars as a function of a date, in order to vary the seasons and their various events (and yes...).

At the bottom of the &quot;Motion-Editor&quot;, a &quot;cam-view&quot; function will give you access to a control panel. Different preview modes are possible. The rendering is also accessible through a window. No less than nine pages compose it. At this level, you will be able to determine the backup name of your images (&quot;path&quot;), the type of texture to be calculated, the resolution of the images, activate or deactivate functions such as the depth buffer (&quot;zbuffer&quot;), the blur, the background image, etc.


Once all these parameters have been set, all you have to do is click on the &quot;Render&quot; button.

For rendering go to Modules and then Render. Select the resolution, then under IMA select the name of the image. Move to FRA and indicate the level of fractal detail which of 4 is quite good. Then Keep to confirm and then reopen the window, pressing Render you will see the result. The image will be opened with any viewing program.


Strengths:

* Multi-window.
* Quality of rendering.
* Accuracy.
* Opening, preview and rendering on CyberGraphX screen.
* Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats 
* The &quot;zbuffer&quot; function.

Weaknesses:

* No OpenGL management 
* Calculation time.
* No network computing tool.


====Writing CD / DVD - Frying Pan====

Can be backup DVDs (4GB ISO size limit due to use of FileInfoBlock), create audio cds from mp3's, and put .iso files on discs

If using for the first time - click Drive button and Device set to ata.device and unit to 0 (zero)

Click Tracks Button - Drive 1 - Create New Disc or Import Existing Disc Image (iso bin/cue etc.) - Session File open cue file

If you're making a data cd, with files and drawers from your hard drive, you should be using the ISO Builder.. which is the MUI page on the left. (&quot;Data/Audio Tracks&quot; is on the right).

You should use the &quot;Data/Audio tracks&quot; page if you want to create music cds with AIFF/WAV/MP3 files, or if you download an .iso file, and you want to put it on a cd.

Click WRITE Button - set write speed - click on long Write button

Examples

Easiest way would be to burn a DATA CD, simply go to &quot;Tracks&quot; page &quot;ISO Builder&quot; and &quot;ADD&quot; everything you need to burn.

On the &quot;Write&quot; page i have &quot;Masterize Disc (DAO)&quot;, &quot;Close Disc&quot; and &quot;Eject after Write&quot; set.

One must not &quot;Blank disc before write&quot; if one uses a CDR


AUDIO CD from MP3's are as easy but tricky to deal with. FP only understands one MP3 format, Layer II, everything else will just create empty tracks

Burning bootable CD's works only with .iso files. Go to &quot;Tracks&quot; page and &quot;Data/Audio Tracks&quot; and add the .iso


====odf====

Every ODF file is a collection of several subdocuments within a package (ZIP file), each of which stores part of the complete document.

* content.xml – Document content and automatic styles used in the content.
* styles.xml – Styles used in the document content and automatic styles used in the styles themselves.
* meta.xml – Document meta information, such as the author or the time of the last save action.
* settings.xml – Application-specific settings, such as the window size or printer information.


To read document follow these steps:

* Extracting .ods file.
* Getting content.xml file (which contains sheets data).
* Creating XmlDocument object from content.xml file.
* Creating DataSet (that represent Spreadsheet file).
* With XmlDocument select “table:table” elements, and then create adequate DataTables.
* Parse child’s of “table:table” element and fill DataTables with those data.
* At the end, return DataSet and show it in application’s interface.


To write document follow these steps:

* Extracting template.ods file (.ods file that we use as template).
* Getting content.xml file.
* Creating XmlDocument object from content.xml file.
* Erasing all “table:table” elements from the content.xml file.
* Reading data from our DataSet and composing adequate “table:table” elements.
* Adding “table:table” elements to content.xml file.
* Zipping that file as new .ods file.

XLS file format

The XLS file format contains streams, substreams, and records.

These sheet substreams include worksheets, macro sheets, chart sheets, dialog sheets, and VBA module sheets. 
All the records in an XLS document start with a 2-byte unsigned integer to specify Record Type (rt), and another for Count of Bytes (cb). A record cannot exceed 8224 bytes. If larger than the rest is stored in one or more continue records.

* Workbook stream 
**Globals substream
***BoundSheet8 record - info for Worksheet substream i.e. name, location, type, and visibility. (4bytes the lbPlyPos FilePointer, specifies the position in the Workbook stream where the sheet substream starts) 
**Worksheet substream (sheet) - Cell Table - Row record - Cells (2byte=row 2byte=column 2byte=XF format)
***Blank cell record
***RK cell record 32-bit number. 
***BoolErr cell record (2-byte Bes structure that may be either a Boolean value or an error code)
***Number cell record (64-bit floating-point number)
***LabelSst cell record (4-byte integer that specifies a string in the Shared Strings Table (SST). Specifically, the integer corresponds to the array index in the RGB field of the SST)
***Formula cell record (FormulaValue structure in the 8 bytes that follow the cell structure. The next 6 bytes can be ignored, and the rest of the record is a CellParsedFormula structure that contains the formula itself)
***MulBlank record (first 2 bytes give the row, and the next 2 bytes give the column that the series of blanks starts at. Next, a variable length array of cell structures follows to store formatting information, and the last 2 bytes show what column the series of blanks ends on)
***MulRK record 
***Shared String Table (SST) contains all of the string values in the workbook.

ACCRINT(), ACCRINTM(), AMORDEGRC(), AMORLINC(), 
COUPDAYBS(), COUPDAYS(), COUPDAYSNC(), COUPNCD(), COUPNUM(), COUPPCD(), 
CUMIPMT(), CUMPRINC(), 
DB(), DDB(), DISC(), 
DOLLARDE(), DOLLARFR(), 
DURATION(), EFFECT(), FV(), FVSCHEDULE(), 
INTRATE(), IPMT(), IRR(), ISPMT(), MDURATION(), MIRR(), NOMINAL(), NPER(), NPV(), 
ODDFPRICE(), ODDFYIELD(), ODDLPRICE(), ODDLYIELD(), 
PMT(), PPMT(), PRICE(), PRICEDISC(), PRICEMAT(), PV(), RATE(), 
RECEIVED(), SLN(), SYD(), TBILLEQ(), TBILLPRICE(), TBILLYIELD(), 
VDB(), XIRR(), XNPV(), YIELD(), YIELDDISC(), YIELDMAT(),


&lt;pre&gt;
&lt;/pre&gt;


&lt;pre&gt;
&lt;/pre&gt;

&lt;pre&gt;
&lt;/pre&gt;

{{BookCat}}</text>
      <sha1>n9w4pd14ox4cmtqm1eqytaex5mz3d35</sha1>
    </revision>
    <revision>
      <id>4669881</id>
      <parentid>4669880</parentid>
      <timestamp>2026-09-13T10:41:57Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669881</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="240482" sha1="qryiirvipzevgciefebx3eplf24bssx" xml:space="preserve">
==Introduction==


[[#Graphical Image Editing Art]]
[[#Office Application]]
[[#Audio]]

[[#Misc Application]]
[[#Games &amp; Emulation]]

[[#Application Guides]]

[[#top|...to the top]]


[[#top|...to the top]]

Most apps can be opened on the Workbench (aka publicscreen pubscreen) which is the default display option but can offer a custom one set to your configurations (aka custom screen mode promotion). These custom ones tend to stack so the possible use of A-M/A-N method of switching between full screens and the ability to pull down screens as well 

If you are interested in creating or porting new software, see [http://en.wikibooks.org/wiki/Aros/Developer/Docs here]

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Internet Applications 
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Web Online Browser [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=network/browser/ Amelinium], Odyssey 2.0, [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1175&amp;highlight=odyssey&amp;rowstart=100 Odyssey 3.0], [], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/comm/www Amelinium], [https://blog.alb42.de/programs/amifox/ amifox] with [https://github.com/alb42/wrp wrp server], IBrowse*, Voyager*, [https://github.com/amigazen/aweb3/ AWeb 3.6 src], [https://github.com/matjam/aweb AWeb Src], [http://aminet.net/package/comm/www/NetSurf-m68k-sources Netsurf], [], 
|&lt;!--AmigaOS4--&gt;[ Odyssey OWB], [ Timberwolf (Firefox port 2011)], [http://amigaworld.net/modules/newbb/viewtopic.php?forum=32&amp;topic_id=32847 OWB-mui], [http://strohmayer.org/owb/ OWB-Reaction], IBrowse*, [http://os4depot.net/index.php?function=showfile&amp;file=network/browser/aweb.lha AWeb], Voyager, [http://www.os4depot.net/index.php?function=browse&amp;cat=network/browser Netsurf], 
|&lt;!--MorphOS--&gt;Wayfarer, [http://fabportnawak.free.fr/owb/ Odyssey OWB], [ Netsurf], IBrowse*, AWeb, [], 
|-
|&lt;!--Sub Menu--&gt;YouTube, Dailymotion website downloading videos audio [https://github.com/yt-dlp/yt-dlp yt-dlp], [https://clipgrab.org/ clipgrab],  
|&lt;!--AROS--&gt;[], [https://blog.alb42.de/amitube/ Amitube], 
|&lt;!--Amiga OS--&gt;[https://blog.alb42.de/amitube/ Amitube], [ smtube], 
|&lt;!--AmigaOS4--&gt;[https://blog.alb42.de/amitube/ Amitube], getVideo, Tubexx, [https://github.com/walkero-gr/aiostreams aiostreams], 
|&lt;!--MorphOS--&gt;[ ytsearch], [https://blog.alb42.de/amitube/ Amitube], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 getVideo], Tubexx 
|-
|&lt;!--Sub Menu--&gt;Old style E-mailing SMTP POP3 IMAP based 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/email SimpleMail], [http://sourceforge.net/projects/simplemail/files/ src], [https://github.com/jens-maus/yam YAM] 
|&lt;!--Amiga OS--&gt;[http://sourceforge.net/projects/simplemail/files/ SimpleMail], [https://github.com/jens-maus/yam YAM]
|&lt;!--AmigaOS4--&gt;SimpleMail, YAM, 
|&lt;!--MorphOS--&gt; SimpleMail, YAM
|-
|&lt;!--Sub Menu--&gt;IRC, ICB, 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat WookieChat], [https://sourceforge.net/projects/wookiechat/ Wookiechat src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat AiRcOS], Jabberwocky, 
|&lt;!--Amiga OS--&gt;Wookiechat, AmIRC 
|&lt;!--AmigaOS4--&gt;Wookiechat 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=5 Wookiechat], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 AmIRC], 
|-
|&lt;!--Sub Menu--&gt;Instant Messaging IM like [https://github.com/BlitterStudio/amidon Hollywood lang based Mastodon client], BlueSky AT protocol, Facebook(TM), Twitter X (TM), Bitlbee IRC Gateway and others 
|&lt;!--AROS--&gt;[https://github.com/kaffeine1/telegram-amiga telegram-amiga], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/chat jabberwocky], 
|&lt;!--Amiga OS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], CLIMM, SabreMSN, jabberwocky, 
|&lt;!--AmigaOS4--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], SabreMSN,
|&lt;!--MorphOS--&gt;[http://amitwitter.sourceforge.net/ AmiTwitter], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 PolyglotNG], SabreMSN,
|-
|&lt;!--Sub Menu--&gt;Torrents 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/p2p ArTorr], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;CTorrent, Transmission 
|&lt;!--MorphOS--&gt;MLDonkey, Beehive, [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Transmission], CTorrent, 
|-
|&lt;!--Sub Menu--&gt;FTP 
|&lt;!--AROS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], MarranoFTP, 
|&lt;!--Amiga OS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://aminet.net/package/comm/tcp/AmiFTP AmiFTP], AmiTradeCenter, ncFTP, 
|&lt;!--AmigaOS4--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|&lt;!--MorphOS--&gt;[https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], [http://morphos.lukysoft.cz/en/vypis.php?kat=5 Pftp], [http://aminet.net/package/comm/tcp/AmiFTP-1.935-OS4 AmiFTP], 
|-
|&lt;!--Sub Menu--&gt;WYSIWYG Web Site Editor
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Internet Radio Streaming Audio [http://www.gnu.org/software/gnump3d/ gnump3d], [http://www.icecast.org/ Icecast2] Server (Broadcast) and Client (Listen), [ mpd], [http://darkice.sourceforge.net/ DarkIce], [http://www.dyne.org/software/muse/ Muse], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc], Mplayer (Icecast Client only), 
|&lt;!--Amiga OS--&gt;[https://github.com/sandlbn/TuneFinder TuneFinder C Src], [https://github.com/sandlbn/TuneFinderMUI TuneFinderMUI], [http://amigazeux.net/anr/ AmiNetRadio], [], [], 
|&lt;!--AmigaOS4--&gt;[http://www.tunenet.co.uk/ Tunenet], 
|&lt;!--MorphOS--&gt;Mplayer, AmiNetRadio, 
|-
|&lt;!--Sub Menu--&gt;VoIP (Voice over IP) with SIP Client (Session Initiation Protocol) or Asterisk IAX2 Clients Softphone (skype like) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;AmiPhone with Speak Freely, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Weather Forecast 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ WeatherBar], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench AWeather], []
|&lt;!--Amiga OS--&gt;[http://amigazeux.net/wetter/ Wetter], [https://github.com/emartisoft/AmiWeatherForecasts AmiWeatherForecasts src], 
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/?function=showfile&amp;file=utility/workbench/flipclock.lha FlipClock], 
|&lt;!--MorphOS--&gt;[http://amigazeux.net/wetter/ Wetter], 
|-
|&lt;!--Sub Menu--&gt;Street Road Maps Route Planning GPS Tracking  
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/muimapparium/ MuiMapparium] [https://build.alb42.de/ Build of MuiMapp versions], 
|&lt;!--Amiga OS--&gt;AmiAtlas*, UKRoutePlus*, [http://blog.alb42.de/ AmOSM], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://blog.alb42.de/programs/mapparium/ Mapparium], 
|-
|&lt;!--Sub Menu--&gt;Clock and Date setting from the internet (either ntp or websites) [https://www.timeanddate.com/worldclock/ World Clock], [http://www.time.gov/ NIST], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc ntpsync],  
|&lt;!--Amiga OS--&gt;ntpsync 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Newsgroups
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[http://newscoaster.sourceforge.net/ Newscoaster], [https://github.com/jens-maus/newsrog NewsRog], [ WorldNews], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;RSS 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/Team-Boingo/AmiRSS AmiRSS src]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;AI
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/murinsel/AmigaAI Claude], [https://github.com/geekychris/amiga_mcp AI on host machine], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BBS
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Graphical Image Editing Art==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Image Editing
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Pixel Raster Artwork [https://github.com/LibreSprite/LibreSprite LibreSprite based on GPL aseprite], [https://github.com/abetusk/hsvhero hsvhero], [], 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/ZunePaint/ ZunePaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit LunaPaint], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit GrafX2], [ LodePaint needs OpenGL], 
|&lt;!--Amiga OS--&gt;[http://www.amigaforever.com/classic/download.html PPaint], GrafX2, [https://github.com/grovdata/Amiga_Sources/blob/master/software.md DeluxePaint], [http://www.amiforce.de/perfectpaint/perfectpaint.php PerfectPaint], Zoetrope, Brilliance2*, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit LodePaint], GrafX2, 
|&lt;!--MorphOS--&gt;Sketch, Pixel*, GrafX2, [http://morphos.lukysoft.cz/en/vypis.php?kat=3 LunaPaint]
|-
|&lt;!--Sub Menu--&gt;Image viewing 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LookHere], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer LoView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer PicShow] , [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--Amiga OS--&gt;PicShow, PicView, Photoalbum,
|&lt;!--AmigaOS4--&gt;WarpView, PicShow, flPhoto, Thumbs, [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], [http://amigaworld.net/modules/newbb/viewtopic.php?mode=viewtopic&amp;topic_id=31400&amp;forum=32&amp;start=80&amp;viewmode=flat&amp;order=0#583458 Picture Album]
|-
|&lt;!--Sub Menu--&gt;Photography retouching / Image Manipulation like Photoshop(tm)  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOEffects], 
|&lt;!--Amiga OS--&gt;[ Tecsoft Video Paint aka TVPaint], Photogenics*, ArtEffect*, ImageFX*, XiPaint, fxPaint, ImageMasterRT, Opalpaint, 
|&lt;!--AmigaOS4--&gt;WarpView, flPhoto, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit Photocrop]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 ShowGirls], ImageFX*, 
|-
|&lt;!--Sub Menu--&gt;Manage RAW picture folder galleries like Darktable, RAWtherapy, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Graphic Format Converter - ICC profile support sRGB, Adobe RGB, XYZ and linear RGB 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;GraphicsConverter, ImageStudio, [http://www.coplabs.org/artpro.html ArtPro]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Thumbnail Generator [], 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/ ZuneView], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/shell Thumbnail Generator]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Icon Editor
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/iconedit Archives], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench Icon Toolbox], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/iconedit IconEditor]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Pixel Art Animation 
|&lt;!--AROS--&gt;Lunapaint
|&lt;!--Amiga OS--&gt;PPaint, AnimatED, Scala*, GoldDisk MovieSetter*, Walt Disney's Animation Studio*, ProDAD*, [https://github.com/historicalsource/DeluxePaint DeluxePaint src], Brilliance
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=3 Titler] 
|-
|&lt;!--Sub Menu--&gt;2D SVG based MovieSetter type 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;MovieSetter*, Fantavision*
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Morphing 
|&lt;!--AROS--&gt;[ GLMorph]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;2D Cad (qcad-&gt;LibreCAD, etc.) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Xcad, MaxonCAD
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Cad like FreeCad, BRL-CAD, OpenSCAD, AvoCADo, etc. using dxf, obj (vertices), blend, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;XCad3d*, DynaCADD*, Cycas, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Model Rendering of glft (json) gbl (png jpg), usdz (USD files with materials, textures, and animations), FBX Filmbox is a proprietary Autodesk format, 
|&lt;!--AROS--&gt;POV-Ray
|&lt;!--Amiga OS--&gt;[http://www.discreetfx.com./amigaproducts.html CINEMA 4D]*, POV-Ray, Lightwave3D*, Real3D*, Caligari24*, Reflections/Monzoom*, [https://github.com/privatosan/RayStorm Raystorm src], Tornado 3D
|&lt;!--AmigaOS4--&gt;Blender, POV-Ray, Yafray
|&lt;!--MorphOS--&gt;Blender, POV-Ray, Yafray
|-
|&lt;!--Sub Menu--&gt;3D Format Converter [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=graphics/convert/ 3doc.i386-aros], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=showfile&amp;file=graphics/convert/ivcon.lha IVCon]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen grabbing display 
|&lt;!--AROS--&gt;[ Screengrabber], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc snapit], [http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record screen recorder], []
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Grab graphics music from apps [https://github.com/Malvineous/ripper6 ripper6], [],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Office Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Office
!width:10%;|AROS (x86)
!width:10%;|[http://en.wikipedia.org/wiki/Amiga_software Commodore-Amiga OS 3.1] (68k)
!width:10%;|[http://en.wikipedia.org/wiki/AmigaOS_4 Hyperion OS4] (PPC)
!width:10%;|[http://en.wikipedia.org/wiki/MorphOS MorphOS] (PPC)
|-
|&lt;!--Sub Menu--&gt;Office Suite 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[ Softwood Final Office], [ Wordworth Office], [ Digita Office],  [ The Works!], [ Europress Mini Office], [], [ Papyrus Office Demo], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Word-processing 
|&lt;!--AROS--&gt;[https://finalwriter.godaddysites.com/ Final Writer 7*], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1995&amp;rowstart=20&amp;pid=12668#post_12668 Slovo], [https://github.com/sodero/MUI-Vim/releases MUI-Vim], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/wordprocessing Cinnamon Writer], [], 
|&lt;!--AmigaOS--&gt;[ Softwood FinalCopy II*], Haage AmigaWriter*, Digita WordWorth*, Softwood FinalWriter*, Micro-Systems Excellence 3*, Arnor Protext, Rashumon, [ InterWord], [ KindWords], [WordPerfect], [ New Horizons Flow], [ CygnusEd Pro], [ Micro-systems Scribble], 
|&lt;!--AmigaOS4--&gt;AbiWord, [ CinnamonWriter], 
|&lt;!--MorphOS--&gt;[ Cinnamon Writer], [http://www.meta-morphos.org/viewtopic.php?topic=1246&amp;forum=53 scriba], [http://morphos.lukysoft.cz/en/index.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Spreadsheets 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/leu/ Leu], [https://archives.arosworld.org/index.php?function=browse&amp;cat=office/spreadsheet ], 
|&lt;!--AmigaOS--&gt;[https://aminet.net/package/biz/spread/ignition-src Ignition Src 1.3], [MaxiPlan 500 Plus], [OXXI Plan/IT v2.0 Speadsheet], [ Superplan], [ Creative Developments TurboCalc], [ ProCalc], [ InterSpread], [Digita DGCalc], [ Gold Disk Advantage], [ Micro-systems Analyze!]
|&lt;!--AmigaOS4--&gt;Gnumeric, [https://ignition-amiga.sourceforge.net/ Ignition], 
|&lt;!--MorphOS--&gt;[ ignition], [http://morphos.lukysoft.cz/en/vypis.php Papyrus Office], 
|-
|&lt;!--Sub Menu--&gt;Presentations
|&lt;!--AROS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, 
|&lt;!--Amiga OS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, MediaPoint, PointRider, Scala*, 
|&lt;!--Amiga OS4--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider 
|&lt;!--MorphOS--&gt;[http://www.hollywoood-mal.com/ Hollywood]*, PointRider
|-
|&lt;!--Sub Menu--&gt;Databases 
|&lt;!--AROS--&gt;[http://sdb.freeforums.org/ SDB], [http://archives.arosworld.org/index.php?function=browse&amp;cat=office/database BeeBase], 
|&lt;!--Amiga OS--&gt;Precision Superbase 4 Pro*, Arnor Prodata*, BeeBase, Datastore, FinalData*, AmigaBase, Fiasco, Twist2*, [Digita DGBase], [], 
|&lt;!--AmigaOS4--&gt;BeeBase, SQLite, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=6 BeeBase], 
|-
|&lt;!--Sub Menu--&gt;PDF Viewing and editing digital signatures 
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/arospdf/ ArosPDF via splash], [https://github.com/wattoc/AROS-vpdf vpdf wip], 
|&lt;!--Amiga OS--&gt;APDF 
|&lt;!--AmigaOS4--&gt;AmiPDF 
|&lt;!--MorphOS--&gt;APDF, vPDF, 
|-
|&lt;!--Sub Menu--&gt;Note Taking markdown support like Obsidian like, joplin, OneNote, EverNotes, xournalpp, etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Study and analyse, collect, organize, annotate, cite, and share
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PIM Personal Information Manager - Day Diary Planner Calendar App 
|&lt;!--AROS--&gt;[ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;Digita Organiser*, On The Ball, Everyday Organiser, [ Contact Manager], 
|&lt;!--AmigaOS4--&gt;AOrganiser, 
|&lt;!--MorphOS--&gt;[http://polymere.free.fr/orga_en.html PolyOrga], 
|-
|&lt;!--Sub Menu--&gt;Accounting
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=office/misc ETB], LoanCalc, [ ], [ ], [ ], 
|[ Digita Home Accounts2], Accountant, Small Business Accounts, Account Master, [ Amigabok], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Project Management Research 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;SuperGantt, SuperPlan, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Desktop 
|&lt;!--AROS--&gt;Wanderer, Scalos, Workbook, DOpus5, 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://github.com/zapek/Ambient Ambient Src]
|-
|&lt;!--Sub Menu--&gt;System Wide Search 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool Finder], [], [], 
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Wide Dictionary - multilingual [http://sourceforge.net/projects/babiloo/ Babiloo], [http://code.google.com/p/stardict-3/ StarDict], 
|&lt;!--AROS--&gt;[ ],  
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System wide Thesaurus - multi lingual
|&lt;!--AROS--&gt;[ ], 
|Kuma K-Roget*, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Sticky Desktop Notes (post it type) 
|&lt;!--AROS--&gt;[http://aminet.net/package/util/wb/amimemos.i386-aros AmiMemos], [https://aminet.net/package/util/wb/amimemos.src-aros AmiMemos Src], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/util/wb/StickIt-2.00 StickIt v2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DTP Desktop Publishing 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit RNOPublisher], 
|&lt;!--Amiga OS--&gt;[http://pagestream.org/ Pagestream]*, Professional Pro Page*, Saxon Publisher, Pagesetter, PenPal, 
|&lt;!--AmigaOS4--&gt;[http://pagestream.org/ Pagestream]* 
|&lt;!--MorphOS--&gt;[http://pagestream.org/ Pagestream]* 
|-
|&lt;!--Sub Menu--&gt;Printing 
|&lt;!--AROS--&gt;Postscript 3 laser printers, [https://github.com/bohunamiga/MintPRINT MintPRINT AirPrint IPP], [ Ghostscript], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/boingball/MintPRINT MintPRINT IPP], [https://github.com/Andiweli/AmiAirprint AmiAirprint], [http://www.irseesoft.de/tp_what.htm TurboPrint]*, [ GutenPrint], [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], [], [], 
|&lt;!--AmigaOS4--&gt;(some native drivers), 
|&lt;!--MorphOS--&gt;early TurboPrint included, [https://aminet.net/package/comm/tcp/NetPrinter NetPrinter LPR], 
|-
|&lt;!--Sub Menu--&gt;Scanning 
|&lt;!--AROS--&gt;[ SCANdal], [], 
|&lt;!--Amiga OS--&gt;FxScan*, ScanQuix* 
|&lt;!--AmigaOS4--&gt;SCANdal (Sane)
|&lt;!--MorphOS--&gt;SCANdal
|-
|&lt;!--Sub Menu--&gt;OCR
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/convert gOCR] 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos-files.net/categories/office/text Tesseract] 
|-
|&lt;!--Sub Menu--&gt;Text Editing
|&lt;!--AROS--&gt;Jano Editor (already installed as Editor), [http://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit EdiSyn], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate], [https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Vim], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd] [https://github.com/vidarh/FrexxEd src], [ NoWinEd], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/text/edit/TurboText20 TurboText20 ttx], Annotate, MicroGoldED/CubicIDE*, CygnusED*, Protext*, NoWinED, 
|&lt;!--AmigaOS4--&gt;Notepad, Annotate, CygnusED*, NoWinED, 
|&lt;!--MorphOS--&gt;MorphOS ED, NoWinED, GoldED/CubicIDE*, CygnusED*, Annotate, 
|-
|&lt;!--Sub Menu--&gt;Office Fonts [http://sourceforge.net/projects/fontforge/files/fontforge-source/ Font Designer] 
|&lt;!--AROS--&gt;[ ], [ ], 
|&lt;!--Amiga OS--&gt;TypeSmith*, SaxonScript (GetFont Adobe Type 1), 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Drawing Vector
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/amifig/ ZuneFIG previously AmiFIG], [https://github.com/serk118/designworks-aros designworks aros 64bit]
|&lt;!--Amiga OS--&gt;Drawstudio*, ProVector*, ArtExpression*, Professional Draw*, AmiFIG, MetaView, [https://gitlab.com/amigasourcecodepreservation/designworks Design Works Src], [], 
|&lt;!--AmigaOS4--&gt;MindSpace, [http://www.os4depot.net/index.php?function=browse&amp;cat=graphics/edit amifig], 
|&lt;!--MorphOS--&gt;SteamDraw, [http://aminet.net/package/gfx/edit/amifig amiFIG], 
|-
|&lt;!--Sub Menu--&gt;video conferencing (jitsi) 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;source code hosting
|&lt;!--AROS--&gt;Gitlab, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (server)
|&lt;!--AROS--&gt;[http://sourceforge.net/projects/zunetools/files/VNC_Server ArosVNCServer], 
|&lt;!--Amiga OS--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC], [http://dspach.free.fr/amiga/avnc/index.html AVNC]
|&lt;!--AmigaOS4--&gt;[http://s.guillard.free.fr/AmiVNC/AmiVNC.htm AmiVNC] 
|MorphVNC, vncserver
|-
|&lt;!--Sub Menu--&gt;Remote Desktop (client) login and connect to another machine 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/zunetools/files/VNC_Client/ ArosVNC], [http://archives.arosworld.org/index.php?function=browse&amp;cat=network/misc rdesktop], 
|&lt;!--Amiga OS--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://dspach.free.fr/amiga/vva/index.html VVA], [http://www.hd-zone.com/ RDesktop]
|&lt;!--AmigaOS4--&gt;[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|[http://twinvnc.free.fr/index.php?menu=01&amp;lang=eng TwinVNC], [http://www.hd-zone.com/ RDesktop]
|-
|&lt;!--Sub Menu--&gt;notifications 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Ranchero 
|&lt;!--AmigaOS4--&gt;Ringhio 
|&lt;!--MorphOS--&gt;MagicBeacon 
|-
|&lt;!--Sub Menu--&gt;Biometric facial logins and fingerprint security features 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Audio==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Audio
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing playback Audio like MP3, [https://github.com/chrg127/gmplayer NSF], [https://github.com/kode54/lazyusf miniusf .usflib] [https://gitlab.com/kode54/psflib with pfslib], [], [], etc 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ HarmonyPlayer hp], [http://www.a500.org/downloads/audio/index.xhtml playcdda] CDs, [ WildMidi Player], [https://bszili.morphos.me/ UADE mod player], [], [ RNOTunes], [ mp3Player], [], 
|&lt;!--Amiga OS--&gt;AmiNetRadio, AmigaAmp, playOGG, [https://codeberg.org/tygre/amimodradio amimodradio]
|&lt;!--AmigaOS4--&gt;TuneNet, SimplePlay, AmigaAmp, TKPlayer
|AmiNetRadio, Mplayer, Kaya, AmigaAmp
|-
|&lt;!--Sub Menu--&gt;Editing Audio 
|&lt;!--AROS--&gt;[ Audio Evolution 4] 
|&lt;!--Amiga OS--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec Src], [http://www.sonicpulse.de/eng/news.html SoundFX], [ Samplitude], 
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/projects/hd-rec/ HD-Rec], AmiSoundED, [http://os4depot.net/?function=showfile&amp;file=audio/record/audioevolution4.lha Audio Evolution 4] 
|[http://www.hd-rec.de/HD-Rec/index.php?site=home HD-Rec], 
|-
|&lt;!--Sub Menu--&gt;Editing Tracker Music
|&lt;!--AROS--&gt;[https://github.com/hitchhikr/protrekkr Protrekkr], [ Schism Tracker], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/tracker MilkyTracker], [http://www.hivelytracker.com/ HivelyTracker], [ Radium in AROS already],  [http://www.a500.org/downloads/development/index.xhtml libMikMod], 
|&lt;!--Amiga OS--&gt;MilkyTracker, HivelyTracker, DigiBooster, Octamed SoundStudio, [https://github.com/elindstrom/soundtracker soundtracker], 
|&lt;!--AmigaOS4--&gt;MilkyTracker, HivelyTracker, GoatTracker
|MilkyTracker, GoatTracker, DigiBooster, 
|-
|&lt;!--Sub Menu--&gt;Editing Music [], [https://github.com/kmatheussen/camd CAMD] and/or staves and musical notes on manuscript 
|&lt;!--AROS--&gt;[http://bnp.hansfaust.de/ Bars and Pipes], [], [], 
|&lt;!--Amiga OS--&gt;[http://bnp.hansfaust.de/ Bars'n'Pipes], MusicX* David &quot;Talin&quot; Joiner &amp; Craig Weeks (for Notator-X), Deluxe Music Construction Set DMCS2*, [https://github.com/timoinutilis/midi-sequencer-amigaos Horny c Src] [https://github.com/kas1e/midi-sequencer-amigaos/tree/master/HornyGCC HornyGCC OS4 src] [https://github.com/capehill/midi-sequencer-amigaos Horny OS4 fork src] [https://www.amigans.net/modules/newbb/viewtopic.php?start=0&amp;topic_id=8143&amp;order=ASC&amp;status=&amp;mode=0 OS4 thread], HD-Rec, [https://aminet.net/package/mus/midi/dominatorV1_51 Dominator], [https://github.com/royaltm/Amiga-midiIn Amiga-midiIn]
|&lt;!--AmigaOS4--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Rockbeat, [http://bnp.hansfaust.de/download.html Bars'n'Pipes], [https://github.com/gooofy/freeaction Horny OS4 src fork], Audio Evolution 4, 
|&lt;!--MorphOS--&gt;Bars'n'Pipes, 
|-
|&lt;!--Sub Menu--&gt;Sound Sampling 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/record Audio Evolution 4], [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;did=162 Quick Record], [https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc SOX to get AIFF 16bit files], [https://github.com/aros-development-team/AROS/tree/master/workbench/tools/AHIRecord AHIRecord], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/mus/edit/AudioEvolution3_src Audio Evolution 3 c src], [ Samplitude]*, Audiomaster IV*, 
|&lt;!--AmigaOS4--&gt;[https://github.com/timoinutilis/phonolith-amigaos phonolith c src], HD-Rec, Audio Evolution 4,
|&lt;!--MorphOS--&gt;[https://sourceforge.net/p/hd-rec/code/HEAD/tree/ HD-Rec Src], Audio Evolution 4,
|-
|&lt;!--Sub Menu--&gt;Audio Processing like easyeffects so having limiter, compressor, convolver, equalizer and auto volume and many other plugins 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Live Looping or Audio Misc - Groovebox like
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;CD/DVD burn
|[https://code.google.com/p/amiga-fryingpan/ FryingPan], 
|&lt;!--Amiga OS--&gt;FryingPan, [http://www.estamos.de/makecd/#CurrentVersion MakeCD], 
|&lt;!--AmigaOS4--&gt;FryingPan, AmiDVD, 
|[http://www.amiga.org/forums/printthread.php?t=58736 FryingPan], Jalopeano, 
|-
|&lt;!--Sub Menu--&gt;CD/DVD audio rip
|Lame, [http://www.imica.net/SitePortalPage.aspx?siteid=1&amp;cfid=0&amp;did=167 Quick CDrip],
|&lt;!--Amiga OS--&gt;Lame,  
|&lt;!--AmigaOS4--&gt;Lame, 
|Lame,  
|-
|&lt;!--Sub Menu--&gt;MP3 v1 and v2 Tagger
|&lt;!--AROS--&gt;id3ren (v1), [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/edit mp3info], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|
|-
|&lt;!--Sub Menu--&gt;Audio Convert
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc Sox], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/mus/misc/SoundBox SoundBox], [http://aminet.net/package/mus/misc/SoundBoxKey SoundBox Key], [http://aminet.net/package/mus/edit/SampleE SampleE], sox 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;DJ mixing jamming 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/djh0ffman/PT1210 Hoffman PT1210 DJ tracker], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Radio Automation Software [http://www.rivendellaudio.org/ Rivendell], [http://code.campware.org/projects/livesupport/report/3 Campware LiveSupport], [http://www.sourcefabric.org/en/airtime/ SourceFabric AirTime], [http://www.ohloh.net/p/mediabox404 MediaBox404], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speakers Audio Sonos Mains AC networked wired controlled 
*2005 ZP100 with ZP80 
*2008 Zoneplayer ZP120 (multi-room wireless amp)  ZP90 receiver only with CR100 controller, 
*2009 ZonePlayer S5, 
*2010 BR100 wireless Bridge (no support),   
*2011 Play:3
*2013 Bridge (no support), Play:1,  
*2016 Arc,   Play:1,   
*Beam (Gen 2),   Playbar,  Ray,   Era 100,   Era 300,   Roam,   Move 2,   
*Sub (Gen 3),   Sub Mini,  Five,  Amp  S2 
|&lt;!--AROS--&gt;SonosController 
|&lt;!--Amiga OS--&gt;SonosController
|&lt;!--AmigaOS4--&gt;SonosController
|&lt;!--MorphOS--&gt;SonosController
|-
|&lt;!--Sub Menu--&gt;Smart Speakers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]

==Video Creativity and Production==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Video
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Playing Video 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/play Mplayer], [ VAMP], [http://www.a500.org/downloads/video/index.xhtml CDXL player], [http://www.a500.org/downloads/video/index.xhtml IffAnimPlay], [], 
|&lt;!--Amiga OS--&gt;Frogger*, AMP2, MPlayer, RiVA*, MooViD*, 
|&lt;!--AmigaOS4--&gt;DvPlayer, MPlayer 
|&lt;!--MorphOS--&gt;MPlayer, Frogger, AMP2, VLC 
|-
|&lt;!--Sub Menu--&gt;Streaming Video and game streaming like OBS studio, Parsec, [https://github.com/lizardbyte/sunshine sunshine], [https://github.com/moonlight-stream/moonlight-qt moonlight], etc 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Playing DVD 
|&lt;!--AROS--&gt;[http://a-mc.biz/ AMC]*, Mplayer 
|&lt;!--Amiga OS--&gt;AMP2, Frogger 
|&lt;!--AmigaOS4--&gt;[http://a-mc.biz/ AMC]*, DvPlayer*, AMP2,  
|&lt;!--MorphOS--&gt;Mplayer 
|-
|&lt;!--Sub Menu--&gt;Screen Recording
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=video/record Screenrecorder], [ ], [ ], [ ], [ ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Screenrecorder, 
|-
|&lt;!--Sub Menu--&gt;Create Edit Individual Video - Amiga like OSs have no pro NLE 
|&lt;!--AROS--&gt;[ Mencoder], [ Quick Videos], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/edit AVIbuild], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc FrameBuild], FFMPEG, 
|&lt;!--Amiga OS--&gt;[ MainConcept Mainactor Broadcast*], [http://en.wikipedia.org/wiki/Video_Toaster Video Toaster*], MacroSystem MovieShop 4.3*, proDAD Adorage*, [ IOSpirit VHI studio]*, [Gold Disk ShowMaker], [], 
|&lt;!--AmigaOS4--&gt;FFMpeg/GUI 
|&lt;!--MorphOS--&gt;Blender, Mencoder, FFmpeg
|-
|&lt;!--Sub Menu--&gt;Subtitle editor 
|&lt;!--AROS--&gt;[https://aminet.net/package/text/edit/Slarti_Arosx86ABIv0 Slarti_Arosx86ABIv0], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;IP-based video production workflows with High Dynamic Range (HDR), 10-bit color collaborative NDI, 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Blogging like Lemmy or kbin
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR face recognition for Vtubers 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting Live2D models with Cubism type editor or [https://github.com/AyagamiDev/ayagami ayagami] like with zipped moc3 with model metadata (model3, cdi3) 
&lt;pre&gt;
Model data (cmo3)
Basic motions (can3)
Background image (png)
Set of files for embedding (runtime folder)
• Model data (moc3)
• Motion data (motion3.json)
• Model settings file (model3.json)
• Physics settings file (physics3.json)
• Display auxiliary file (cdi3.json)
&lt;/pre&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;VR chatting chatters .VRML models - standardized 3D file format for VR avatars 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;V-tubers V-tubing like Vseeface with Openseeface tracker or Vpuppr (virtual puppet project) for online live 2d / 3d art models rigging rigged LIV 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.

[[#top|...to the top]]


==Misc Application==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1 (68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;File Management 
|&lt;!--AROS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 DOpus Magellan aka DOpus 5], [ Scalos], [ ], 
|&lt;!--Amiga OS--&gt;DOpus2, DOpus 4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], ClassAction, FileMaster, [http://www.amiga.org/forums/showthread.php?t=4897 DirWork 2]*, [https://github.com/RudolphRiedel/DiskMaster2 DiskMaster2 src], 
|&lt;!--AmigaOS4--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], Filer, AmiDisk 
|&lt;!--MorphOS--&gt;DOpus4, [https://github.com/BlitterStudio/dopus5 Dopus5 Magellan], 
|-
|&lt;!--Sub Menu--&gt;File Verification / Repair 
|&lt;!--AROS--&gt;[https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility md5sum], [https://arosarchives.os4depot.net/index.php?function=browse&amp;cat=utility/filetool asum], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/filetool workpar2] (PAR2),  [http://zakalwe.fi/~shd/foss/cksfv/files/ compile cksfv from website], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;Par2, 
|-
|Application Installer 
|&lt;!--AROS--&gt;[], [ InstallerNG], 
|&lt;!--Amiga OS--&gt;InstallerNG, Grunch, 
|&lt;!--AmigaOS4--&gt;Jack
|&lt;!--MorphOS--&gt;Jack 
|-
|&lt;!--Sub Menu--&gt;Compression archiver [https://github.com/FS-make-simple/paq9a paq9a], [], 
|&lt;!--AROS--&gt;XAD system is a toolkit designed for handling various file and disk archiver
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[https://aminet.net/package/util/pack/decrunchmania_os4 Crunchmania CrM2 depacker], 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Binary Hexadecimal Editor 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/edit Zaphod], [],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Partition Editor formatter Disk Management
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1440&amp;highlight=partition&amp;pid=8821#post_8821 QuickPart], [ HDToolBox]
|&lt;!--Amiga OS--&gt;[https://github.com/stefanskotte/hdpart hdpart], [https://github.com/ChuckyGang/AmiPart AmiPart], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Filesystem Repair and backups 
|&lt;!--AROS--&gt;ArSFSDoctor, 
|&lt;!--Amiga OS--&gt;[https://aminet.net/package/disk/bakup/quarterback_src Quarterback Tools C and asm src], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;System Disk check, integrity and history [https://github.com/smartmontools/smartmontools smart tools], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Multiple File renaming
|&lt;!--AROS--&gt;DOpus 4 or 5, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Anti Virus
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;VChecker, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Random Wallpaper Desktop changer [ DOpus5], [ Scalos],  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Alarm Clock, Timer, Stopwatch, Countdown 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/workbench DClock], [http://aminet.net/util/time/AlarmClockAROS.lha AlarmClock], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 2==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;C/C++ IDE Integrated Development 
|&lt;!--AROS--&gt;[https://sourceforge.net/projects/aidea/ AIDEa], [ Murks], [],  
|&lt;!--Amiga OS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, [ StormC], [https://github.com/jens-maus/amide amide], [], 
|&lt;!--AmigaOS4--&gt;CodeBench , [https://gitlab.com/boemann/codecraft CodeCraft], 
|&lt;!--MorphOS--&gt;[http://devplex.awardspace.biz/cubic/index.html Cubic IDE]*, 
|-
|&lt;!--Sub Menu--&gt;C/C++ Text Editors 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit FrexxEd], [https://github.com/vidarh/FrexxEd FrexxEd src], [http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/text/edit Annotate] with [https://www.onyxsoft.se/files/annotate_src.lha src], 
|&lt;!--Amiga OS--&gt;[ Protext], [ CED], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[https://www.onyxsoft.se/annotate.html Annotate], 
|-
|&lt;!--Sub Menu--&gt;Repository
|&lt;!--AROS--&gt;[ Git]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;Git
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;BASIC Computer Language 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/language Basic4SDL], [ Ace Basic], [ X-AMOS], [SDLBasic], [ Alvyn], 
|&lt;!--Amiga OS--&gt;[http://www.amiforce.de/main.php Amiblitz 3] with [https://github.com/AmiBlitz/AmiBlitz3 Asm src], [http://amos.condor.serverpro3.com/AmosProManual/contents/c1.html Amos Pro] with [https://github.com/AmiDARK/AmosProfessionalUnity-Official-Releases Asm src], [http://aminet.net/package/dev/basic/ace24dist ACE Basic], [https://github.com/gooofy/aqb aqb], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;sdlBasic
|-
|&lt;!--Sub Menu--&gt;Computer Languages Translation [https://tetracorp.github.io/guide/reverse-engineering-amiga.html], [https://amigasourcecodepreservation.gitlab.io/amiga-assembler-insider-guide/], [https://github.com/kermitfrog/Amiga-Re-Engineering Rust, Ghidra and FS-UAE], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://bitbucket.org/rhinoid/convert68000toc/src/main/ convert m68k seka asm-one to c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Gui Creators
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=development/guitool MuiBuilder], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[ MuiBuilder],  
|-
|&lt;!--Sub Menu--&gt;Catalog .cd .ct Custom App Language Editors 
|&lt;!--AROS--&gt;FlexCat, [https://archives.arosworld.org/index.php?function=browse&amp;cat=utility Flexcat GUI], [], 
|&lt;!--Amiga OS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|&lt;!--AmigaOS4--&gt;[http://aminet.net/package/dev/misc/simplecat SimpleCat], FlexCat
|&lt;!--MorphOS--&gt;[http://www.geit.de/deu_simplecat.html SimpleCat], FlexCat
|-
|&lt;!--Sub Menu--&gt;Cross Development 
|&lt;!--AROS--&gt;[], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/geekychris/amiga_mcp amiga_mcp], [https://github.com/mbergmann-sh/AmigaED4-IDE AmigaED4-IDE], [https://lemonspawn.com/turbo-rascal-syntax-error-expected-but-begin/ Turbo Rascal], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Misc Application 3==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;System 
|&lt;!--AROS--&gt;[ SysExplorer], [ SysMon], [ Scout], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Terminals Shells CLIs 
|&lt;!--AROS--&gt;[https://tomaszstaniak.com/aros-term/ aros-term], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;OSK On Screen Keyboard
|&lt;!--AROS--&gt;[], 
|&lt;!--Amiga OS--&gt;[https://aminet.net/util/wb/OSK.lha OSK]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Magnifier Magnifying Glass Magnification 
|&lt;!--AROS--&gt;[http://www.onyxsoft.se/files/zoomit.lha ZoomIT], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Comic Book CBR CBZ format reader viewer 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comics], [http://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/viewer comicon], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Reader 
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#legadon Legadon EPUB],[]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Ebook Converter 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Text to Speech tts [https://github.com/JonathanFly/bark-installer Bark], [], 
|&lt;!--AROS--&gt;[ Echo &quot; &quot; &gt;SPEAK:A1 inbuilt], [http://archives.arosworld.org/index.php?function=browse&amp;cat=audio/misc flite], 
|&lt;!--Amiga OS--&gt;[http://www.text2speech.com translator], [https://github.com/sidick/narrator.wyoming narrator.wyoming], [], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=search&amp;tool=simple FLite]
|&lt;!--MorphOS--&gt;[http://se.aminet.net/pub/aminet/mus/misc/ FLite]
|-
|&lt;!--Sub Menu--&gt;Speech Voice Recognition Dictation - [http://sourceforge.net/projects/cmusphinx/files/ CMU Sphinx], [http://julius.sourceforge.jp/en_index.php?q=en/index.html Julius], [http://www.isip.piconepress.com/projects/speech/index.html ISIP], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Speech Voice Changer [], [], [], [], 
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Screen Display Blanker screensaver 
|&lt;!--AROS--&gt;Blanker Commodity (built in), [https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/screenblanker GarshneBlanker], [http://sourceforge.net/projects/gblanker/ GBlanker Src], [], 
|&lt;!--Amiga OS--&gt;MultiCX, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;ModernArt Blanker, 
|-
|&lt;!--Sub Menu--&gt;Fortune Cookie Quotes Sayings 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/misc AFortune], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}


==Misc Application 4==
{|  class=&quot;wikitable sortable&quot; 
|- 
!width:30%;|Misc Application
!width:10%;|AROS(x86)
!width:10%;|Commodore-Amiga OS 3.1(68k)
!width:10%;|Hyperion OS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Fractals mandelbrot, etc 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/misc], 
|&lt;!--Amiga OS--&gt;ZoneXplorer, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Landscape Rendering 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=graphics/raytrace WCS World Construction Set], 
|&lt;!--Amiga OS--&gt;[ Vista Pro], [http://en.wikipedia.org/wiki/World_Construction_Set World Construction Set]
|&lt;!--AmigaOS4--&gt;[ WCS World Construction Set],
|&lt;!--MorphOS--&gt;[ WCS World Construction Set],
|-
|&lt;!--Sub Menu--&gt;Astronomy [https://sourceforge.net/projects/skychart/ skychart freepascal], [], [], 
|&lt;!--AROS--&gt;[ Digital Almanac (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/search?query=planetarium Aminet search], [http://aminet.net/misc/sci/DA3V56ISO.zip Digital Almanac], [https://aminet.net/package/misc/sci/da3sourceV58 Src c V58], [ Galileo renamed to Distant Suns]*, [], 
|&lt;!--AmigaOS4--&gt;[http://sourceforge.net/projects/digital-almanac/ Digital Almanac], Distant Suns*, [http://www.digitaluniverse.org.uk/ Digital Universe]*,
|&lt;!--MorphOS--&gt;[http://www.aminet.net/misc/sci/da3.lha Digital Almanac], [http://www.aminet.net/package/misc/sci/da3-mos-src Src c V56], 
|-
|&lt;!--Sub Menu--&gt;Astrology [https://sourceforge.net/projects/skylendar/ skylendar], [https://github.com/CruiserOne/Astrolog Astrolog], [https://www.astrolog.org/astrolog/astfile.htm Astrology alt site], [https://saravali.github.io/download.html Maitreya], [https://github.com/alamahant/Asteria Asteria], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Genealogy History Family Tree Ancestry Records (FreeBMD, FreeREG, and FreeCEN file formats or GEDCOM GenTree)
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt; [ Origins], [ Your Family Tree], [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Languages 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;Fun School, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;https://github.com/evil4dmin/ami2ha
|-
|&lt;!--Sub Menu--&gt;Mathematics ([http://www-fourier.ujf-grenoble.fr/~parisse/install_en.html Xcas], etc.), 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/scientific mathX] 
|&lt;!--Amiga OS--&gt;Maple V, mathX, Fun School, GCSE Maths, [ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;Yacas 
|&lt;!--MorphOS--&gt;Yacas 
|-
|&lt;!--Sub Menu--&gt;Maths Graph Function Plotting
|&lt;!--AROS--&gt;[https://blog.alb42.de/programs/#MUIPlot MUIPlot], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;App Utility Launcher Dock toolbar  
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=utility/docky BoingBar], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/adkennan/DockBot Dockbot],
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;3D Printer [https://github.com/OrcaSlicer/OrcaSlicer OrcaSlicer]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;PCB design
|&lt;!--AROS--&gt; 
|&lt;!--Amiga OS--&gt;[ ], [ ], [ ], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Digital Signage
|&lt;!--AROS--&gt;Hollywood, Hollywood Designer 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;HAM radio, amateur radio, packet radio,  [], [], [], [https://cemaxecuter.com/ Dragon OS], [https://github.com/km4ack/73Linux with 73 link update], [https://www.youtube.com/watch?v=YAL5KNePRSg video for], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/punktniklas/NiKom NiKom], [https://www.amigarealm.com/amiga/amicomms/comm4.htm Comm4], [https://www.amigarealm.com/archives/comms/aarug/ TNC Terminal Node Controller with packets over serial connections on Yaesu or Woxum handheld], [https://aminet.net/comm/misc AmiCom], [ with 7Plus file encoder/decoder], [ mksstv], [ RTTYam], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;modern smart-home network like Home Assistant Automation Yellow, Green, Mosquitto, EMQX,  
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;[https://github.com/evil4dmin/ami2ha HA], [https://github.com/sidick/midge mtqq.lib], [https://aminet.net/package/comm/tcp/AmiHomeassist-0.7 AmiHomeassist], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Teaching classroom learning training [https://github.com/moodle/moodle moodle], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

&lt;nowiki&gt;*&lt;/nowiki&gt; Commercial product.


==Games &amp; Emulation==

Some emulators/games require OpenGL to function and to adjust ahi prefs channels, frequency and unit0 and unit1 and 
[http://aros.sourceforge.net/documentation/users/shell/changetaskpri.php changetaskpri -1]

Rom patching  https://www.marcrobledo.com/RomPatcher.js/ https://www.romhacking.net/patch/ (ips, ups, bps, etc) and this other site supports the latter formats https://hack64.net/tools/patcher.php 

Free public domain roms for use with emulators can be found [http://www.pdroms.de/ here] as most of the rest are covered by copyright rules. If you like to read about old games see [http://retrogamingtimes.com/ here] and [http://www.armchairarcade.com/neo/ here] and a [http://www.vintagecomputing.com/ blog] about old computers. Possibly some of the [http://www.answers.com/topic/list-of-best-selling-computer-and-video-games best selling] of all time. [http://en.wikipedia.org/wiki/List_of_computer_system_emulators Wiki] with emulated systems list.

[https://archive.gamehistory.org/ Archive of VGHF], [https://library.gamehistory.org/ Video Game History Foundation Library search]


{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Emulation]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|-
|&lt;!--Sub Menu--&gt;Games Emulation Amstrad CPC 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [ Caprice32 (OpenGL &amp; pure SDL)], [ Arnold], [https://retroshowcase.gr/cpcbox-master/], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Apple2 and 2GS
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Arcade 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Mame], [ SI Emu (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;Mame, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem xmame], amiarcadia, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 Mame], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 2600 [], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Stella], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 5200 [https://github.com/wavemotion-dave/A5200DS A5200DS], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 7800
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari 400 800 130XL [https://github.com/wavemotion-dave/A8DS A8DS], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Atari800], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Lynx
|&lt;!--AROS--&gt;[http://myfreefilehosting.com/f/6366e11bdf_1.93MB Handy (ABIv0 only)], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Atari Jaguar
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Bandai Wonderswan 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation BBC Micro and Acorn Electron [http://beehttps://bem-unix.bbcmicro.com/download.html BeebEm], [http://b-em.bbcmicro.com/ B-Em], [http://elkulator.acornelectron.co.uk/ Elkulator], [http://electrem.emuunlim.com/ ElectrEm], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Dragon 32 and Tandy CoCo [http://www.6809.org.uk/xroar/ xroar], [], 
|&lt;!--AROS--&gt;[], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C16 Plus4
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore C64
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Vice (ABIv0 only)], [], 
|&lt;!--Amiga OS--&gt;Frodo, 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem viceplus], 
|&lt;!--MorphOS--&gt;Vice, 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Commodore Amiga
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Janus UAE], Emumiga, 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://os4depot.net/index.php?function=browse&amp;cat=emulation/computer UAE], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=2 UAE], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Japanese MSX MSX2 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Intelivision
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Mattel Colecovision and Adam
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Milton Bradley (MB) Vectrex [ Vectrex OpenGL], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation PICO8 Pico-8 fantasy video game console [https://github.com/egordorichev/pemsa-sdl/ pemsa-sdl], [https://github.com/jtothebell/fake-08 fake-08], [https://github.com/Epicpkmn11/fake-08/tree/wip fake-08 fork], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo Gameboy
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem vba no sound], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem vba]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo NES
|&lt;!--AROS--&gt;[ EmiNES], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Fceu], [https://github.com/takahirox/nes-js?tab=readme-ov-file nes-js], [https://github.com/bfirsh/jsnes jsnes], [https://github.com/angelo-wf/NesJs NesJs], 
|&lt;!--Amiga OS--&gt;AmiNES, [http://www.dridus.com/~nyef/darcnes/ darcNES], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem amines]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo SNES
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Zsnes], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem warpsnes]
|&lt;!--MorphOS--&gt;[http://fabportnawak.free.fr/snes/ Snes9x], 
|-
|&lt;!--Sub Menu--&gt;Games Emulation Nintendo N64 
*HLE and plugins [ mupen64], [https://github.com/ares-emulator/ares ares], [https://github.com/N64Recomp/N64Recomp N64Recomp], [https://github.com/rt64/rt64 rt64], [https://github.com/simple64/simple64 Simple64], 
*LLE [], 
|&lt;!--AROS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+],
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/mupen64plus/ Mupen64+], [http://aminet.net/package/misc/emu/tr-981125_src TR64], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Gamecube Wii]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Nintendo Wii U]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/yuzu-emu Nintendo Switch]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation NEC PC Engine 
|&lt;!--AROS--&gt;[], [], [https://github.com/yhzmr442/jspce js-pce], 
|[http://www.hugo.fr.fm/ Hugo], [http://mednafen.sourceforge.net/ Mednafen], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem tgemu]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Master System (SMS)
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem Dega], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem sms], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem osmose]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Genesis/Megadrive
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem gp no sound], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem DGen], 
|&lt;!--Amiga OS--&gt;[http://code.google.com/p/genplus-gx/ Genplus], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem genesisplus]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Saturn 
*HLE [https://mednafen.github.io/ mednafen], [http://yabause.org/ yabause], [], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;[http://yabause.org/ Yabause], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sega Dreamcast 
*HLE [https://github.com/flyinghead/flycast  flycast], [https://code.google.com/archive/p/nulldc/downloads NullDC], 
*LLE [], [], 
|&lt;!--AROS--&gt;?
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair ZX80 and ZX81 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair Spectrum 
|[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Fuse (crackly sound)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer SimCoupe], [ FBZX slow], [https://jsspeccy.zxdemo.org/ jsspeccy], [http://torinak.com/qaop/games qaop], 
|&lt;!--Amiga OS--&gt;[http://www.lasernet.plus.com/ Asp], [http://www.zophar.net/sinclair.html Speculator], [http://www.worldofspectrum.org/x128/index.html X128], 
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/computer]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sinclair QL
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], [], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/QDOS4amiga1 QDOS4amiga]
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation SNK NeoGeo Pocket
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem gngeo], NeoPop, 
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation Sony PlayStation
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/gamesystem FPSE], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem FPSE]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS2]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[ Sony PS3]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://vita3k.org/ Sony Vita]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;[https://github.com/shadps4-emu/shadPS4 PS4]
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation [http://en.wikipedia.org/wiki/Tangerine_Computer_Systems Tangerine] Oric and Atmos 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer Oricutron]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.os4depot.net/index.php?function=browse&amp;cat=emulation/gamesystem Oricutron]
|&lt;!--MorphOS--&gt;[http://aminet.net/package/misc/emu/oricutron Oricutron]
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 99/4 99/4A [https://github.com/wavemotion-dave/DS994a DS994a], [], [https://js99er.net/#/ js99er], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=emulation/computer], 
|&lt;!--Amiga OS--&gt;[http://aminet.net/package/misc/emu/TI4Amiga TI4Amiga], [http://aminet.net/package/misc/emu/TI4Amiga_src TI4Amiga src in c], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation HP 38G 40GS 48 49G/50G Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Emulation TI 58 83 84 85 86 - 89 92 Graphing Calculators
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|}

{|  class=&quot;wikitable sortable&quot; 
|- 
!width:10%;|Games [https://www.rockpapershotgun.com/ General]
!width:10%;|AROS(x86)
!width:10%;|AmigaOS3(68k)
!width:10%;|AmigaOS4(PPC)
!width:10%;|MorphOS(PPC)
|- style=&quot;background:lightgrey;{{text default color}}; text-align:center; font-weight:bold;&quot;
| Games [https://www.trackawesomelist.com/michelpereira/awesome-open-source-games/ Open Source and others] || AROS || Amiga OS || Amiga OS4 || Morphos 
|-
|&lt;!--Sub Menu--&gt;Games Action like [https://github.com/opentomb/OpenTomb opentomb], [https://github.com/LostArtefacts/TRX TRX formerly Tomb1Main], [https://github.com/TombEngine TombEngine], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Thrust], [https://github.com/fragglet/sdl-sopwith sdl sopwith], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/action], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action BOH], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/BSzili/OpenLara/tree/amiga/src source of openlara SDL2], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Adventure like [http://dotg.sourceforge.net/ DMJ], [https://github.com/kromenak/gengine Gabriel Knight 3], [http://www.sarien.net/ Sierra Sarien], [https://github.com/klembot/twinejs twine js], [https://github.com/QSPFoundation/qspgui Quest Soft Player QSP], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/adventure dmagnetic], [https://archives.arosworld.org/?function=browse&amp;cat=emulation/misc ScummVM], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying frotz infocom], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Board like [https://github.com/aperture-software/colditz-escape escape from colditz], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/board], [http://amigan.1emu.net/releases Africa]
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Cards 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/card], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12934#post_12934 Balatro], 
|&lt;!--AmigaOS--&gt;[http://home.arcor.de/amigasolitaire/e/welcome.html Reko], [https://github.com/samskivert/beschei-en beschei Src], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Misc [https://github.com/michelpereira/awesome-open-source-games Awesome open], [https://github.com/bobeff/open-source-games General Open Source], [https://github.com/SAT-R/sa2 Sonic Advance 2], [https://github.com/velorek1/cwordle Wordle type], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games FPS like [https://aminet.net/package/game/shoot/D1X_Rebirth_AGA Descent D1X src], [https://github.com/DescentDevelopers/Descent3 Descent 3], [https://github.com/Fewnity/Counter-Strike-Nintendo-DS Counter-Strike-Nintendo-DS], [https://github.com/Aleph-One-Marathon/alephone Bungie Marathon 1994], [https://zdoom.org/downloads UzDoom opengl 3.3], [https://github.com/ZDoom/gzdoom gzdoom opengl 3+], [https://zdoom.org/downloads LZDoom opengl 2.1], 
|&lt;!--AROS--&gt;Doom, Quake, [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Quake 3 Arena (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Assault Cube (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Cube 2 Sauerbraten (OpenGL)], [http://fodquake.net/test/ FodQuake QuakeWorld], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Duke Nukem 3D], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Darkplaces Nexuiz Xonotic], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Doom 3 SDL (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Hexenworld and Hexen 2], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Aliens vs Predator Gold 2000 avp (openGL)], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/fps Odamex (openGL doom)], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ zgloom], [], [https://archives.arosworld.org/?function=showfile&amp;file=game/fps/ ab3dhd], [], 
|&lt;!--Amiga OS--&gt;Doom, Quake, AB3D, Fears, Breathless, Gloom, 
|&lt;!--AmigaOS4--&gt;Doom, Quake, 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12 Doom], Quake, Quake 3 Arena, [https://github.com/OpenXRay/xray-16 S.T.A.L.K.E.R Xray]
|-
|&lt;!--Sub Menu--&gt;Games MMORG like 
|&lt;!--AROS--&gt;[ Eternal Lands (OpenGL)],
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Platform like 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform], [ Maze of Galious], [ Gish]*(openGL), [ Mega Mario], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ thextech SMBX], [http://www.gianas-return.de/ Giana's Return], [http://www.sqrxz.de/ Sqrxz], [www.sqrxz2.de/ Sqrxz 2], [http://www.sqrxz.de/sqrxz-3/ Sqrxz 3], [http://www.sqrxz.de/sqrxz-4/ Sqrxz 4], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/platform Cave Story], [https://bszili.morphos.me/ Frogatto], [https://bszili.morphos.me/ OpenJazz], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ pekkakana2], [ Aquaria], [https://archives.arosworld.org/?function=showfile&amp;file=game/platform/ sonic CD], [], 
|&lt;!--Amiga OS--&gt;[ Giana Sisters], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Puzzle [https://github.com/mariopartyrd/marioparty4/tree/port Party], [https://github.com/mdodis/OpenSolomonsKey OpenSolomonsKey], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle], [ Cubosphere (OpenGL)], [http://archives.arosworld.org/index.php?function=browse&amp;cat=game/puzzle Candy Crisis], [http://bszili.morphos.me/ TailTale], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Racing [ Trigger Rally], [ VDrift], [http://www.ultimatestunts.nl/index.php?page=2&amp;lang=en Ultimate Stunts], [http://maniadrive.raydium.org/ Mania Drive], [https://github.com/plowteam/donut Simpsons Hit and Run], [], 
|&lt;!--AROS--&gt;[ Super Tux Kart (OpenGL)], [http://www.dusabledanslherbe.eu/AROSPage/F1Spirit.30.html F1 Spirit (OpenGL)], [http://bszili.morphos.me/index.html MultiRacer], [https://bszili.morphos.me/ Speed Dreams], [https://archives.arosworld.org/?function=showfile&amp;file=game/driving/dethrace-0.10.1.x86_64-aros-v11.zip Carmageddon dethrace 64bit], [], 
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://bszili.morphos.me/index.html Speed Dreams], 
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12], [http://bszili.morphos.me/index.html TORCS], 
|-
|&lt;!--Sub Menu--&gt;Games 1st first person DRPG [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/OpenEnroth/OpenEnroth OpenEnroth MM], []
|&lt;!--AROS--&gt;[https://github.com/BSzili/aros-stuff Arx Libertatis], [http://www.playfuljs.com/a-first-person-engine-in-265-lines/ js raycaster], [https://github.com/Dorthu/es6-crpg webgl], [https://github.com/sonountaleban/AmiShockolate System Shock], [], [], 
|&lt;!--AmigaOS--&gt;Phantasie, Faery Tale, Dungeon Master, 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 3rd third person action CRPG  [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/alexbatalov/fallout1-ce fallout ce], [https://github.com/rwengine/openrw gta3], [https://github.com/gta-reversed/gta-reversed gta3 sa], [https://github.com/mrxenginner/reVC gta3 vc revc], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ fheroes2 homm2], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ breakhack], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ devilutionx diablo 1 hellfire], [https://archives.arosworld.org/?function=showfile&amp;file=game/roleplaying/ fallout 1], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ stratagus], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ hostile-takeover], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games isometric RPG [https://sourceforge.net/projects/sumwars/ Summoning Wars], [https://www.solarus-games.org/ Solarus], [https://wiki.rpg.net/index.php/Open_Game_Systems Misc], [https://github.com/topics/dungeon?l=javascript Dungeon], [], [https://github.com/clintbellanger/heroine-dusk JS Dusk], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying nethack], [https://archives.arosworld.org/index.php?function=browse&amp;cat=game/roleplaying GemRB], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games card based RPG [https://github.com/open-duelyst/duelyst Duelyst], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games turn based tactics RPG [], [], [], [], [], [], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy UFO AI], [http://play.freeciv.org/ FreeCiv], [], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Strategy [http://rtsgus.org/ RTSgus], [http://stargus.sourceforge.net/ Stargus], [https://github.com/KD-lab-Open-Source/Perimeter Perimeter], [https://matty77.itch.io/conflict-3049 conflict-3049], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=game/strategy MegaGlest (OpenGL)], [https://archives.arosworld.org/?function=showfile&amp;file=game/strategy/ signus], [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=140&amp;pid=12446#post_12446 Wargus warcraft 2 setup], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Rhythm, Beat, Step [], [], [https://clonehero.net/ clonehero], [https://github.com/MatteoGodzilla/Dj-Engine Dj-Engine], 
|&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/misc Frets on Fire], [], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Shoot Em Ups [http://www.mhgames.org/oldies/formido/ Formido], [http://code.google.com/p/violetland/ Violetland], 
||&lt;!--AROS--&gt;[https://archives.arosworld.org/index.php?function=browse&amp;cat=game/action Open Tyrian], [http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ Alien Blaster], [https://github.com/OpenFodder/openfodder OpenFodder], [https://archives.arosworld.org/?function=showfile&amp;file=game/action/ tbftss The Battle for the Solar System: the Pandora War]
|&lt;!--AmigaOS--&gt;
|&lt;!--AmigaOS4--&gt;[http://www.parallelrealities.co.uk/projects/starfighter.php Starfighter], [ The Battle for the Solar System: the Pandora War]
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Simulations [http://scp.indiegames.us/ Freespace 2], [http://www.heptargon.de/gl-117/gl-117.html GL117], [http://code.google.com/p/corsix-th/ Theme Hospital], [http://code.google.com/p/freerct/ Rollercoaster Tycoon], [http://hedgewars.org/ Hedgewars], [https://github.com/raceintospace/raceintospace raceintospace], [https://github.com/Return-To-The-Roots RTTR Settlers 2], [https://github.com/OoliteProject/oolite oolite elite], [https://github.com/fesh0r/newkind newkind elite], [https://github.com/bohemiainteractive/cwr Arma Cold War Src], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;SimCity, SimAnt, Sim Hospital, Theme Park, [https://github.com/angree/openttd_amiga_68k openttd amiga_68k], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;[http://morphos.lukysoft.cz/en/vypis.php?kat=12]
|-
|&lt;!--Sub Menu--&gt;Games Life Sim [https://github.com/ACreTeam/forest Animal Crossing], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Horror [https://github.com/Mikompilation/MikuPan Fatal Frame], [ ], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Sandbox Voxel Open World Exploration [https://github.com/ClassiCube/ Classicube],[http://www.michaelfogleman.com/craft/ Craft], [https://github.com/tothpaul/DelphiCraft DelphiCraft],[https://www.minetest.net/ Luanti formerly Minetest], [ infiniminer], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Battle Royale [https://bruh.io/ Play.Bruh.io], [https://www.coolmathgames.com/0-copter Copter Royale], [https://surviv.io/ Surviv.io], [https://nuggetroyale.io/#Ketchup Nugget Royale], [https://miniroyale2.io/ Miniroyale2.io], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Tower Defense [https://chriscourses.github.io/tower-defense/ HTML5], [https://github.com/SBardak/Tower-Defense-Game TD C++], [https://github.com/bdoms/love_defense LUA and LOVE], [https://github.com/HyOsori/Osori-WebGame HTML5], [https://github.com/PascalCorpsman/ConfigTD ConfigTD Pascal], [https://github.com/GloriousEggroll/wine-ge-custom Wine], []
|&lt;!--AROS--&gt;[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=1443&amp;rowstart=180&amp;pid=12871#post_12871 Plants vs Zombies PvZ], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Visual Novel Engines [https://github.com/diane1f0cd/VisualNovelTemplate Visual Novel Template], [https://github.com/Kirilllive/tuesday-js Tuesday JS], [https://github.com/tejasnayak25/vnsutra vnsutra], [https://github.com/weetabix-su/renpsp-dev RenPSP], [https://github.com/Galladite27/ONScripter-EN ONScripter-EN], [https://github.com/NathanGuilhot/VNES-Raylib https://github.com/NathanGuilhot/VNES VNES in Raylib], [https://www.renpy.org/latest.html renpy ren'py python based], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Reality VR [https://gitlab.com/madsbuvi/openmw openmw vr], [https://github.com/Team-Beef-Studios/BeefRaiderXR BeefRaiderXR], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Table Top VTT [ Roll20], [https://www.owlbear.rodeo/ owlbear rodeo], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Computer assisted TableTop TTRPG OSR [https://www.rpgsolo.com/play.php RPGSolo], [https://github.com/fpsvogel/solo-ttrpgs Solo TTRPG], [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games 2D 3D Engines [https://github.com/fegennari/3DWorld 3DWorld], [https://github.com/GarageGames/Torque3D Torque3D], [https://github.com/gameplay3d/GamePlay GamePlay 3D],  [https://www.babylonjs.com/ BabylonJS ], [ Godot], [ Ogre], [ Crystal Space], [https://github.com/JacobHess03/ Dragon-Quest like], [https://github.com/bjornbytes/lovr Lua LOVE for 2D LOVR for 3D], [], 
|&lt;!--AROS--&gt;[https://www.arkhamdev.net/wiki.htm?id=agx Arkham Development antiryadgx 8.9 lts with register], [], 
|&lt;!--Amiga OS--&gt;[https://github.com/alpyre/Sevgi_Engine Sevgi Engine], [], [], 
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games C based game frameworks [https://github.com/orangeduck/Corange Corange], [https://github.com/scottcgi/Mojoc Mojoc], [https://orx-project.org/ Orx], [https://github.com/ioquake/ioq3 Quake 3], [https://www.mapeditor.org/ Tiled], [https://www.raylib.com/ 2d Raylib], [https://github.com/Rabios/awesome-raylib other raylib], [https://github.com/MrFrenik/gunslinger Gunslinger], [https://o3de.org/ o3d], [http://archives.aros-exec.org/index.php?function=browse&amp;cat=development/library GLFW], [], 
|&lt;!--AROS--&gt;[http://archives.arosworld.org/index.php?function=browse&amp;cat=development/library Raylib 5], 
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games RPGMaker MV/MZ-compatible projects [https://github.com/Psychronic-Games/RPGReactor RPGReactor js],
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games Virtual Pinball [https://github.com/vpinball/vpinball vpinball], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|-
|&lt;!--Sub Menu--&gt;Games unpack unarc [], [], 
|&lt;!--AROS--&gt;
|&lt;!--Amiga OS--&gt;
|&lt;!--AmigaOS4--&gt;
|&lt;!--MorphOS--&gt;
|}


==Application Guides==

[[#top|...to the top]]

===Web Browser===

OWB is now at version 2.0 (which got an engine refresh, from July 2015 to February 2019) and 3.0.

This latest version has a good support for many/most web sites, even YouTube web page now works. [https://www.bilibili.tv/en/search untested] 

This improved compatibility comes at the expense of higher RAM usage (now 1GB RAM is the absolute minimum). 

Also, keep in mind that the lack of a JIT (Just-In-Time) JS compiler on the 32 bit version, makes the web surfing a bit slow. 

Only the 64 bit version of OWB 2.0 will have JIT enabled, thus benefitting of more speed. There are tooltypes that can be added to the icon to provide further features JIT, MSE etc 


Certificates from [https://curl.se/docs/caextract.html ca certs], 


DNS tracking blocking with [https://easylist.to/easylist/easylist.txt easylist.txt] in PROGDIR:Conf before starting browser with enabled AdBlock [https://github.com/easylist/easylist/tree/master easylist], [https://gitlab.com/eyeo anti abp], [https://firebog.net/ big blocklist], [https://github.com/StevenBlack/hosts Steves], [], [], 

This can be enabled with OWB Odyssey with Windows -&gt; Content Blocking and Windows -&gt; Messages and enter 

 https://www.youtube.com/api/stats/ads*
 https://www.youtube.com/pagead/adview*
 https://www.youtube.com#@##player-ads*

into your custom filters 


Element blocker browser extension might be needed for [https://github.com/easylist/easylist/wiki/Youtube-Issues youtube], [ mid roll], [ pre roll], [ ],  


OWB speed is much better when running from RAM Disk, the best way is to add the below into your S:User-Startup which copies OWB drawer from Extras:Internet/OWB to RAM Disk: 

So add this :
&lt;pre&gt;
copy Extras:Internet/OWB Ram:OWB/ ALL CLONE &gt;NIL:
copy Extras:Internet/OWB.info Ram: &gt;NIL:
&lt;/pre&gt;
Open RAM Disk and open OWB drawer and double click on OWB icon so that the above icon tooltypes are activated 

Problems are that the copy time is long (around 20 seconds added in the background), but we can make it faster if we delete useless files from the OWB drawer (docs, …)
If you don’t copy the drawer back onto the HD, you won’t save your cache, cookies, passwords… So you need a script for it.


Error messages 

SSL error &quot;cant verify with ca-certificates&quot;, check bios clock time date is correct 

Error 6, try checking networking prefs settings and Save / Use preferences again or a '''few times''' otherwise the network chipset may not be compatible with Aros 


[https://www.google.com/search?q=%s&amp;udm=14 Google search without AI overview] 


===E-mail===

 YAM does not support SSL and most mail providers now switched to encrypted SMTP/POP3 connections


====SimpleMail====

SimpleMail supports IMAP and appears to work with GMail, but it's never been reliable enough, it can crash with large mailboxes.

Please read more on this [http://www.freelists.org/list/simplemail-usr User list]


 GMail

Be sure to activate the pop3 usage in your gmail account setup / configuration first.

pop3: 
pop.gmail.com
Use SSL: Yes
Port: 995

smtp:
smtp.gmail.com (with authentication)
Use Authentication: Yes
Use SSL: Yes
Port: 465 or 587


 Hotmail/MSN/outlook/Microsoft Mail mid-2017, all outlook.com accounts will be migrated to Office 365 / Exchange

Most users are currently on POP which does not allow showing folders and many other features (technical limitations of POP3). With Microsoft IMAP you will get folders, sync read/unread, and show flags. You still won't get push though, as Microsoft has not turned on the IMAP Idle command as at Sept 2013.

If you want to try it, you need to first remove (you can't edit) your pop account (long-press the account on the accounts screen, delete account). Then set it up this way:

1. Email/Password
2. Manual
3. IMAP
4.

* Incoming: imap-mail.outlook.com, port 993, SSL/TLS should be checked
* Outgoing: smtp-mail.outlook.com, port 587, SSL/TLS should be checked
* POP server name pop-mail.outlook.com, port 995, POP encryption method SSL

 Yahoo  Mail

On April 24, 2002 Yahoo ceased to offer POP access to its free mail service. Introducing instead a yearly payment feature, allowing users POP3 and IMAP server support, along with such benefits as larger file attachment sizes and no adverts.

Sorry to see Yahoo leaving its users to cough up for the privilege of accessing their mail. Understandable, when competing against rivals such as Gmail and Hotmail who hold a large majority of users and were hacked in 2014 as well.


Incoming Mail (IMAP) Server

* Server - imap.mail.yahoo.com
* Port - 993
* Requires SSL - Yes

Outgoing Mail (SMTP) Server

* Server - smtp.mail.yahoo.com
* Port - 465 or 587
* Requires SSL - Yes
* Requires authentication - Yes

Your login info

* Email address - Your full email address (name@domain.com)
* Password - Your account's password
* Requires authentication - Yes


Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a subscription subs fee to have access to SMTP and POP3

* Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
* “Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
* “Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
* “Password” – Your Yahoo Mail password.

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

* Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.


====YAM Yet Another Mailer====

 YAM does not support SSL and most mail providers have now switched to encrypted SMTP/POP3 connections

This email client is POP3 only if the SSL library is available [http://www.freelists.org/list/yam YAM Freelists]

One of the downsides of using a POP3 mailer unfortunately - you have to set an option not to delete the mail if you want it left on the server. IMAP keeps all the emails on the server.

Possible issues

Sending mail issues is probably a matter of using your ISP's SMTP server, though it could also be an SSL issue.


getting a &quot;Couldn't initialise TLSv1 / SSL error

Use of on-line e-mail accounts with this email client is not possible as it lacks the OpenSSL AmiSSl v3 compatible library

 GMail 
Incoming Mail (POP3) Server - requires SSL: pop.gmail.com
Use SSL: Yes
Port: 995

Outgoing Mail (SMTP) Server - requires TLS: smtp.gmail.com (use authentication)
Use Authentication: Yes
Use STARTTLS: Yes (some clients call this SSL)
Port: 465 or 587

Account Name: your Gmail username (including '@gmail.com')
Email Address: your full Gmail email address (username@gmail.com)
Password: your Gmail password

Anyway, the SMTP is pop.gmail.com port 465 and it uses SSLLv3 Authentication. The POP3 settings are for the same server (pop.gmail.com), only on port 995 instead.


 Outlook.com access

&lt;pre &gt;
Outlook.com SMTP server address: smtp.live.com
Outlook.com SMTP user name: Your full Outlook.com email address (not an alias)
Outlook.com SMTP password: Your Outlook.com password
Outlook.com SMTP port: 587
Outlook.com SMTP TLS/SSL encryption required: yes 
&lt;/pre &gt;


 Yahoo  Mail

&lt;pre &gt;
“POP3 Server” – Set the POP server for incoming mails as pop.mail.yahoo.com. You will have to enable “SSL” and use 995 for Port.
“SMTP Server” – Set the SMTP server for outgoing mails as smtp.mail.yahoo.com. You will also have to make sure that “SSL” is enabled and use 465 for port. you must also enable “authentication” for this to work.
“Account Name or Login Name” – Your Yahoo Mail ID i.e. your email address without the domain “@yahoo.com”.
“Email Address” – Your Yahoo Mail address i.e. your email address including the domain “@yahoo.com”. E.g. myname@yahoo.com
“Password” – Your Yahoo Mail password.
&lt;/pre &gt;

Yahoo! Mail Plus users may have to set POP server as plus.pop.mail.yahoo.com and SMTP server as plus.smtp.mail.yahoo.com.

Note that you need to enable “Web &amp; POP Access” in your Yahoo Mail account to send and receive Yahoo Mail messages through any other email program.

You will have to enable “Allow your Yahoo Mail to be POPed” under “POP and Forwarding”, to send and receive Yahoo mails through any other email client.

Cannot be done since 2002 unless the customer pays Yahoo a monthly fee to have access to SMTP and POP3


 Microsoft Outlook Express Mail 

1. Get the files to your PC.
By whatever method get the files off your Amiga onto your PC. In the YAM folder you have a number of different folders, one for each of your folders in YAM. Inside that is a file usually some numbers such as 332423.283. YAM created a new file for every single email you received.

2. Open up a brand new Outlook Express. Just configure the account to use 127.0.0.1 as mail servers. It doesn't really matter. You will need to manually create any subfolders you used in YAM.

3. You will need to do a mass rename on all your email files from YAM. Just add a .eml to the end of it. Amazing how PCs still rely mostly on the file name so it knows what sort of file it is rather than just looking at it! There are a number of multiple renamers online to download and free too.

4. Go into each of your folders, inbox, sent items etc. And do a select all then drag the files into Outlook Express (to the relevant folder obviously) Amazingly the file format that YAM used is very compatible with .eml standard and viola your emails appear. With correct dates and working attachments.

5. If you want your email into Microsoft Outlook. Open that up and create a new profile and a new blank PST file. Then go into File Import and choose to import from Outlook Express. And the mail will go into there. And viola.. you have your old email from your Amiga in a more modern day format.


===FTP===

Magellan has a great FTP module. It allows transferring files from/to a FTP server over the Internet or the local network and, even if FTP is perceived as a &quot;thing of the past&quot;, its usability is all inside the client. The FTP thing has a nice side effect too, since every Icaros machine can be a FTP server as well, and our files can be easily transferred from an Icaros machine to another with a little configuration effort.

First of all, we need to know the 'server' IP address. Server is the Icaros machine with the file we are about to download on another Icaros machine, that we're going to call 'client'. To do that, move on the server machine and 1) run Prefs/Services to be sure &quot;FTP file transfer&quot; is enabled (if not, enable it and restart Icaros); 2) run a shell and enter this command:

ifconfig -a

Make a note of the IP address for the network interface used by the local area network. For cabled devices, it usually is net0:. Now go on the client machine and run Magellan:

Perform these actions: 1) click on FTP; 2) click on ADDRESS BOOK; 3) click on &quot;New&quot;. 
You can now add a new entry for your Icaros server machine:

1) Choose a name for your server, in order to spot it immediately in the address book. Enter the IP address you got before.

2) click on Custom Options:


1) go to Miscellaneous in the left menu;

2) Ensure &quot;Passive Transfers&quot; is NOT selected;

3) click on Use. We need to deactivate Passive Transfers because YAFS, the FTP server included in Icaros, only allows active transfers at the current stage. Now, we can finally connect to our new file source:


1) Look into the address book for the newly introduced server, be sure that name and IP address are right, and

2) click on Connect. A new lister with server's &quot;MyWorkspace&quot; contents will appear. You can now transfer files over the network choosing a destination among your local (client's) volumes.

Can be adapted to any FTP client on any platform of your choice, just be sure your client allows Active Transfers as well.


===IRC Internet Relay Chat===

Jabberwocky is ideal for one-to-one social media communication, use IRC if you require one to many. 

Just type a message in ''lowercase''' letters and it will be posted to all in the [ AROS irc channel]. Please do not use UPPER CASE as it is a sign of SHOUTING which is annoying.

Other things to type in - replace &lt;message&gt; with a line of text and &lt;nick&gt; with a person's name

&lt;pre&gt;
/help

/list

/who
/whois &lt;nick&gt;

/msg &lt;nick&gt; &lt;message&gt;

/query &lt;nick&gt; 
&lt;message&gt;s
/query

/away &lt;message&gt;
/away

/quit &lt;going away message&gt; 
&lt;/pre&gt;


[http://irchelp.org/irchelp/new2irc.html#smiley Intro guide here]. IRC Primer can be found here in [http://www.irchelp.org/irchelp/ircprimer.html html], [http://www.irchelp.org/irchelp/text/ircprimer.txt TXT], [http://www.kei.com/irc/IRCprimer1.1.ps PostScript].


Issue the command /me &lt;text&gt; where &lt;text&gt; is the text that should follow your nickname.
Example: /me slaps ajk around a bit with a large trout

/nick &lt;newNick&gt;

/nickserv register &lt;password&gt; &lt;email address&gt;

/ns instead of /nickserv, while others might need /msg nickserv

/nickserv identify &lt;password&gt;

Alternatives:
/ns identify &lt;password&gt;
/msg nickserv identify &lt;password&gt;


==== IRC WookieChat ====

WookieChat is the most complete internet client for communication across the IRC Network. WookieChat allows you to swap ideas and communicate in real-time, you can also exchange Files, Documents, Images and everything else using the application's DCC capabilities.


add smilies drawer/directory

 run wookiechat from the shell and set stack to 1000000 e.g. wookiechat stack 1000000

select a server / server window

* nickname 
* user name 
* real name - optional

Once you configure the client with your preferred screen name, you'll want to find a channel to talk in.


servers

* New Server - click on this to add / add extra - change details in section below this click box 
* New Group
* Delete Entry
* Connect to server
* connect in new tab
* perform on connect

Change details

* Servername - change text in this box to one of the below Server: 
* Port number - no need to change
* Server password
* Channel - add #channel from below 
* auto join - can click this 
* nick registration password,

Click Connect to server button above


&lt;pre&gt;
Server: irc.freenode.net
Channel: #aros
&lt;/pre&gt;

irc://irc.freenode.net/aros

&lt;pre&gt;
Server: chat.amigaworld.net 
Channel: #amigaworld or #amigans 
&lt;/pre&gt;

&lt;pre&gt;
On Sunday evenings USA time usually starting around 3PM EDT (1900 UTC)
Server:irc.superhosts.net
Channel #team*amiga  
&lt;/pre&gt;

&lt;pre&gt;
BitlBee and Minbif are IRCd-like gateways to multiple IM networks
Server: im.bitlbee.org 
Port 6667 
Seems to be most useful on WookieChat as you can be connected to several servers at once. One for Bitlbee and any messages that might come through that. One for your normal IRC chat server. 
&lt;/pre&gt;

[http://www.bitlbee.org/main.php/servers.html Other servers],

&lt;pre&gt;
#Amiga.org - irc.synirc.net eu.synirc.net dissonance.nl.eu.synirc.net (IPv6: 2002:5511:1356:0:216:17ff:fe84:68a) 
twilight.de.eu.synirc.net zero.dk.eu.synirc.net us.synirc.net avarice.az.us.synirc.net envy.il.us.synirc.net harpy.mi.us.synirc.net 
liberty.nj.us.synirc.net snowball.mo.us.synirc.net - Ports 6660-6669 7001 (SSL)
&lt;/pre&gt;

&lt;pre&gt;
Multiple server support
&quot;Perform on connect&quot; scripts and channel auto-joins
Automatic Nickserv login
Tabs for channels and private conversations
CTCP PING, TIME, VERSION, SOUND
Incoming and Outgoing DCC SEND file transfers
Colours for different events
Logging and automatic reloading of logs
mIRC colour code filters
Configurable timestamps
GUI for changing channel modes easily
Configurable highlight keywords
URL Grabber window
Optional outgoing swear word filter
Event sounds for tabs opening, highlighted words, and private messages
DCC CHAT support
Doubleclickable URL's
Support for multiple languages using LOCALE
Clone detection
Auto reconnection to Servers upon disconnection
Command aliases
Chat display can be toggled between AmIRC and mIRC style
Counter for Unread messages
Graphical nicklist and graphical smileys with a popup chooser
&lt;/pre&gt;


====IRC Aircos ====

Double click on Aircos icon in Extras:Networking/Apps/Aircos. It has been set up with a guest account for trial purposes. Though ideally, choose a nickname and password for frequent use of irc. 


====IRC and XMPP Jabberwocky====
 Servers are setup and close down at random 
You sign up to a server that someone else has setup and access chat services through them. 

The two ways to access chat from jabberwocky
&lt;pre &gt;
Jabberwocky -&gt; Server -&gt; XMPP -&gt; open and ad-free 
Jabberwocky -&gt; Server -&gt; Transports (Gateways) -&gt; Proprietary closed systems 
&lt;/pre &gt;

The Jabber.org service connects with all IM services that use XMPP, the open standard for instant messaging and presence over the Internet. The services we connect with include Google Talk (closed), Live Journal Talk, Nimbuzz, Ovi, and thousands more. However, you can not connect from Jabber.org to proprietary services like AIM, ICQ, MSN, Skype, or Yahoo because they don’t yet use XMPP components (XEP-0114) '''but''' you can use Jabber.com's servers and IM gateways (MSN, ICQ, Yahoo etc.) instead.

The best way to use jabberwocky is in conjunction with a public jabber server with '''transports''' to your favorite services, like gtalk, Facebook, yahoo, ICQ, AIM, etc.


You have to register with one of the servers, [https://list.jabber.at/ this list] or [http://www.jabberes.org/servers/ another list], [http://xmpp.net/ this security XMPP list],

Unfortunately jabberwocky can only connect to one server at a time so it is best to check what services each server offers. If you set it up with separate Facebook and google talk accounts, for example, sometimes you'll only get one or the other.

Jabberwocky open a window where the Jabber server part is typed in as well as your Nickname and Password.

Jabber ID (JID) identifies you to the server and other users.

Once registered the next step is to goto Jabberwocky's &quot;Windows&quot; menu and select the &quot;Agents&quot; option. The &quot;Agents List&quot; window will open.

Roster (contacts list)

[http://search.wensley.org.uk/ Chatrooms] (MUC) are available

File Transfer - can send and receive files through the Jabber service but not with other services like IRC, ICQ, AIM or Yahoo. All you need is an installed webbrowser and OpenURL.

Clickable URLs - The message window uses Mailtext.mcc and you can set a URL action in the MUI mailtext prefs like SYS:Utils/OpenURL %s NEWWIN.

There is no consistent Skype like (H.323 VoIP) video conferencing available over Jabber. The move from xmpp to Jingle should help but no support on any amiga-like systems at the moment. [http://aminet.net/package/dev/src/AmiPhoneSrc192 AmiPhone] and [http://www.lysator.liu.se/%28frame,faq,nobg,useframes%29/ahi/v4-site/ Speak Freely] was an early attempt voice only contact. SIP and Asterisk are other PBX options.


 Facebook

If you're using the XMPP transport provided by Facebook themselves, chat.facebook.com, it looks like they're now requiring SSL transport. This means jabberwocky method below will no longer work. The best thing to do is to create an ID on a public jabber server which has a Facebook gateway.

&lt;pre &gt;
1. launch jabberwocky
2. if the login window doesn't appear on launch, select 'account' from the jabberwocky menu
3. your jabber ID will be user@chat.facebook.com where user is your user ID
4. your password is your normal facebook password
5. to save this for next time, click the popup gadget next to the ID field

6. click the 'add' button
7. click the 'close' button
8. click the 'connect' button
&lt;/pre &gt;

you're done. you can also click the 'save as default account' button if you want. jabberwocky configured to auto-connect when launching the program, but you can configure as you like. there is amigaguide documentation included with jabberwocky.

[http://amigaworld.net/modules/newbb/viewtopic.php?topic_id=37085&amp;forum=32 Read more here]

for Facebook users, you can log-in directly to Facebook with jabberwocky. just sign in as @chat.facebook.com with your Facebook password as the password


 Twitter

For a few years, there has been added a twitter transport. Servers include [http://jabber.hot-chilli.net/ jabber.hot-chili.net],  and .

An [http://jabber.hot-chilli.net/tag/how-tos/ How-to]

:Read [http://jabber.hot-chilli.net/2010/05/09/twitter-transport-working/ more]

 Instagram 

no support at the moment best to use a web browser based client

 ICQ

The new version (beta) of StriCQ uses a newer ICQ protocol. Most of the ICQ Jabber Transports still use an older ICQ protocol. You can only talk one-way to StriCQ using the older Transports. Only the newer ICQv7 Transport lets you talk both ways to StriCQ. Look at the server lists in the first section to check.

Register on a Jabber server, e.g. this one works: http://www.jabber.de/
Then login into Jabberwocky with the following login data e.g. xxx@jabber.de / Password: xxx Now add your ICQ account under the window-&gt;Agents-&gt;&quot;Register&quot;. Now Jabberwocky connects via the Jabber.de server with your ICQ account.

 Yahoo Messenger

although yahoo! does not use xmpp protocol, you should be able to use the transport methods to gain access and post your replies

 MSN

early months of 2013 Microsoft will ditch MSN Messenger client and force everyone to use Skype...but MSN protocol and servers will keep working as usual for quite a long time....

Occasionally the Messenger servers have been experiencing problems signing in.  You may need to sign in at www.outlook.com and then try again.  It may also take multiple tries to sign in.  (This also affects you if you’re using Skype.)

You have to check each servers' Agents List to see what transports (MSN protocol, ICQ protocol, etc.) are supported or use the list address' provided in the section above. Then register with each transport (IRC, MSN, ICQ, etc.) to which you need access. After registering you can Connect to start chatting.

msn.jabber.com/registered should appear in the window.

From this [http://tech.dir.groups.yahoo.com/group/amiga-jabberwocky/message/1378 JW group] guide which  helps with this process in a clear, step by step procedure.

1. Sign up on MSN's site for a passport account. This typically involves getting a Hotmail address.

2. Log on to the Jabber server of your choice and do the following:

* Select the &quot;Windows/Agents&quot; menu option in Jabberwocky.
* Select the MSN Agent from the list presented by the server.
* Click the Register button to open a new window asking for:
**Username = passort account email address, typically your hotmail address.
**Nick = Screen name to be shown to anyone you add to your buddy list.
**Password = Password for your passport account/hotmail address.
* Click the Register button at the bottom of the new window.

3. If all goes well, you will see the MSN Gateway added to your buddy list. If not, repeat part 2 on another server. Some servers may show MSN in their list of available agents, but have not updated their software for the latest protocols used by MSN.

4. Once you are registered, you can now add people to your buddy list. Note that you need to include the '''msn.''' ahead of the servername so that it knows what gateway agent to use. Some servers may use a slight variation and require '''msg.gate.''' before the server name, so try both to see what works.

If my friend's msn was amiga@hotmail.co.uk and my jabber server was @jabber.meta.net.nz..
then amiga'''%'''hotmail.com@'''msn.'''jabber.meta.net.nz

or another the trick to import MSN contacts is that you don't type the hotmail URL but the passport URL... e.g. Instead of: goodvibe%hotmail.com@msn.jabber.com  You type: goodvibe%passport.com@msn.jabber.com 
And the thing about importing contacts I'm afraid you'll have to do it by hand, one at the time...

 Google Talk

any XMPP server will work, but you have to add your contacts manually. a google talk user is typically either @gmail.com or @talk.google.com. a true gtalk transport is nice because it brings your contacts to you and (can) also support file transfers to/from google talk users.

implement Jingle a set of extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP)

support ended early 2014 as Google moved to Google+ Hangouts which uses it own proprietary format


===Video Player MPlayer===

Many of the menu features (such as doubling) do not work with the current version of mplayer but using

4:3
 mplayer -vf scale=800:600 file.avi

16:9
 mplayer -vf scale=854:480 file.avi

if you want gui use;
 mplayer -gui 1 &lt;other params&gt; file.avi

&lt;pre &gt;
stack 1000000

; using AspireOS 1.xx 
; copy FROM SYS:Extras/Multimedia/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 1.x 
; copy FROM SYS:Tools/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

; using Icaros Desktop 2.x 
; copy FROM SYS:Utilities/MPlayer/ TO RAM:MPlayer ALL CLONE &gt; Nil:

cd RAM:MPlayer
run MPlayer -gui &gt; Nil:
;run MPlayer -gui -ao ahi_dev -playlist http://www.radio-paralax.de/listen.pls &gt; Nil: 
&lt;/pre &gt;

$ mplayer rtsp://127.0.0.1:554/sample_300kbit.mp4


MPlayer supports multicast streaming, and rtp/rtsp protocols (it might require [http://www.live555.com/openRTSP/ live555 library] to work with some streams). But you might have to build it where it's disabled. Also, multicast won't work with some AmiTCP-likes. MIAMI supported it, though.

AROS supports IPv4 (old but works) and this includes the needed address space for RTP.

If you mean multicast via RTP - mplayer handles it. You can even force UDP over TCP

-rtsp-stream-over-tcp

If the rtsp Real Time Streaming Protocol  server needs authentification:

-user -passwd


MPlayer - Menu - Open Playlist and load already downloaded .pls or .m3u file - auto starts around 4 percent cache

MPlayer - Menu - Open Stream and copy one of the .pls lines below into space allowed, press OK and press play button on main gui interface


Old 8bit 16bit remixes chip tune game music 
 
http://www.radio-paralax.de/listen.pls 

http://scenesat.com/

http://www.shoutcast.com/radio/Amiga

http://www.theoldcomputer.com/retro_radio/RetroRadio_Main.htm

http://www.kohina.com/

http://www.remix64.com/

http://retrogamer.net/forum/

http://retroasylum.podomatic.com/rss2.xml

http://retrogamesquad.com/

http://www.retronauts.com/

http://monsterfeet.com/noquarter/

http://www.retrogamingradio.com/

http://www.radiofeeds.co.uk/mp3.asp


[[#top|...to the top]]

====ZunePaint==== 

simplified typical workflow

* importing and organizing and photo management
* making global and regional local correction(s) - recalculation is necessary after each adjustment as it is not in real-time 
* exporting your images in the best format available with the preservation of metadata


Whilst achieving 80% of a great photo with just a filter, the remaining 20% comes from a manual fine-tuning of specific image attributes.


For photojournalism, documentary, and event coverage, minimal touching is recommended. Stick to Camera Raw for such shots, and limit changes to level adjustment, sharpness, noise reduction, and white balance correction.

For fashion or portrait shoots, a large amount of adjustment is allowed and usually ends up far from the original. Skin smoothing, blemish removal, eye touch-ups, etc. are common.  Might alter the background a bit to emphasize the subject.

Product photography usually requires a lot of sharpening, spot removal, and focus stacking.

For landscape shots, best results are achieved by doing the maximum amount of preparation before/while taking the shot. No amount of processing can match timing, proper lighting, correct gear, optimal settings, etc. Excessive post-processing might give you a dramatic shot but best avoided in the long term.


* White Balance - Left Amiga or F12 and K and under &quot;Misc color effects&quot; tab with a pull down for White Balance - color temperature also known as AKA tint (movies) or tones (painting) - warm temp raise red reduce green blue - cool raise blue lower red green 
* Exposure - exposure compensation, highlight/shadow recovery
* Noise Reduction - during RAW development or using external software
* Lens Corrections - distortion, vignetting, chromatic aberrations
* Detail - capture sharpening and local contrast enhancement
* Contrast - black point, levels (sliders) and curves tools (F12 and K) 
* Framing - straighten () and crop (F12 and F) 
* Refinements - color adjustments and selective enhancements - Left Amiga or F12 and K for RGB and YUV histogram tabs - 
* Resizing - enlarge for a print or downsize for the web or email (F12 and D) 
* Output Sharpening - customized for your subject matter and print/screen size


White Balance - F12 and K

scan your image for a shade which was meant to be white (neutral with each RGB value being equal) like paper or plastic which is in the same light as the subject of the picture. Use the dropper tool to select this color, similar colours will shift and you will have selected the perfect white balance for your part of the image - for the whole picture make sure RAZ or CLR button at the bottom is pressed before applying to the image above.


Exposure correction

F12 and K - YUV Y luminosity - RGB extra red tint - move red curve slightly down and move blue green curves slightly up

Workflows in practice

* Undo - Right AROS key or F12 and Z 
* Redo - Right AROS key or F12 and R

First flatten your image (if necessary) and then do a rotation until the picture looks level. 
* Crop the picture. Click the selection button and drag a box over the area of the picture you want to keep. Press the crop button and the rest of the photo will be gone. 
* Adjust your saturation, exposure, hue levels, etc., (right AROS Key and K for color correction) until you are happy with the photo. Make sure you zoom in all of the way to 100% and look the photo over, zoom back out and move around. Look for obvious problems with the picture. 
* After coloring and exposure do a sharpen (Right AROS key and E for Convolution and select drop down option needed), e.g. set the matrix to 5x5 (roughly equivalent Amount to 60%) and set the Radius to 1.0. Click OK.


And save your picture


Implemented or would like to see for simplification and ease of use

basic filters (presets) like black and white, monochrome, edge detection (sobel), motion/gaussian blur, 
* negative, sepiatone, retro vintage, night vision, colour tint, color gradient, color temperature, glows, fire, lightning, lens flare, emboss, filmic, pixelate mezzotint, antialias, etc.

adjust / cosmetic tools such as crop, 
* reshaping tools, straighten, smear, smooth, perspective, liquify, bloat, pucker, push pixels in any direction, dispersion, transform like warp, blending with soft light, page-curl, whirl, ripple, fisheye, neon,  etc. 
* red eye fixing, blemish remover, skin smoothing, teeth whitener, make eyes look brighter, desaturate,

effects like oil paint, cartoon, pencil sketch, charcoal, noise/matrix like sharpen/unsharpen, (right AROS key with A for Artistic effects) 
* blend two image, gradient blend, masking blend, explode, implode, custom collage, surreal painting, comic book style, needlepoint, stained glass, watercolor, mosaic, stencil/outline, crayon, chalk, etc.

borders such as 
* dropshadow, rounded, blurred, color tint, picture frame, film strip polaroid, bevelled edge, etc.

brushes e.g.
* frost, smoke, etc.

and manual control of

fix lens issues including vignetting (darkening), color fringing and barrel distortion, and chromatic and geometric aberration -  lens and body profiles

perspective correction

levels - directly modify the levels of the tone-values of an image, by using sliders for highlights, midtones and shadows

curves -  Color Adjustment and Brightness/Contrast

color balance

one single color transparent (alpha channel (color information/selections) for masking and/or blending ) for backgrounds, etc.

Threshold indicates how much other colors will be considered mixture of the removed color and non-removed colors

decompose layer into a set of layers with each holding a different type of pattern that is visible within the image

any selection using any selecting tools like lasso tool, marquee tool etc. the selection will temporarily be save to alpha 
If you create your image without transparency then the Alpha channel is not present, but you can add later.

File formats like .psd (Photoshop file has layers, masks etc.  contains edited sensor data. The original sensor data is no longer available) .xcf .raw .hdr

Image Picture Formats
* low dynamic range (JPEG, PNG, TIFF 8-bit), 16-bit (PPM, TIFF), typically as a 16-bit TIFF in either ProPhoto or AdobeRGB colorspace -  TIFF files are also fairly universal – although, if they contain proprietary data, such as Photoshop Adjustment Layers or Smart Filters, then they can only be opened by Photoshop making them proprietary.
* linear high dynamic range (HDR) images (PFM, [http://www.openexr.com/ ILM .EXR], jpg, [http://aminet.net/util/dtype cr2] (canon tiff based), hdr, NEF, CRW, ARW, MRW, ORF, RAF (Fuji), PEF, DCR, SRF, ERF, DNG files are RAW converted to an Adobe proprietary format - a container that can embed the raw file as well as the information needed to open it) 
An old version of [http://archives.aros-exec.org/index.php?function=browse&amp;cat=graphics/convert dcraw]

There is no single RAW file format. Each camera manufacturer has one or more unique RAW formats. RAW files contain the brightness levels data captured by the camera sensor. This data cannot be modified. A second smaller file, separate XML file, or within a database with instructions for the RAW processor to change exposure, saturation etc. The extra data can be changed but the original sensor data is still there. RAW is technically least compatible.

A raw file is high-bit (usually 12 or 14 bits of information) but a camera-generated TIFF file will be usually converted by the camera (compressed, downsampled) to 8 bits. The raw file has no embedded color balance or color space, but the TIFF has both. These three things (smaller bit depth, embedded color balance, and embedded color space) make it so that the TIFF will lose quality more quickly with image adjustments than the raw file. The camera-generated TIFF image is much more like a camera processed JPEG than a raw file. A strong advantage goes to the raw file. The power of RAW files, such as the ability to set any color temperature non-destructively and will contain more tonal values.

The principle of preserving the maximum amount of information to as late as possible in the process. The final conversion - which will always effectively represent a &quot;downsampling&quot; - should prevent as much loss as possible.

Once you save it as TIFF, you throw away some of that data irretrievably. When saving in the lossy JPEG format, you get tremendous file size savings, but you've irreversibly thrown away a lot of image data. As long as you have the RAW file, original or otherwise, you have access to all of the image data as captured.

Keyboard equivalence with Photoshop(tm) would help 

File
PHOTOSHOP	SHORTCUT	GIMP
New	Ctrl+n	New
Open	Ctrl+o	Open
Close	Ctrl+w	Close
Save	Ctrl+s	Save
Save as	Shift+Ctrl+s	Save as
Revert	F12	Revert
Print	Ctrl+p	Print
Exit	Ctrl+q	Quit
 
Edit
PHOTOSHOP	SHORTCUT	GIMP
Undo/Redo (1 level)	Ctrl+z	Undo (Redo is Shift+Ctrl+z)
Cut	Ctrl+x	Cut
Copy	Ctrl+c	Copy
Paste	Ctrl+v	Paste
Paste Into	Shift+Ctrl+v	Paste Into
Fill with FG color	Alt+Backspace	Fill with FG color
Fill with BG color	Control+Backspace	Fill with BG color
 
Image/Colors
PHOTOSHOP	SHORTCUT	GIMP
Levels	Ctrl+l	Levels
Auto Contrast	Shift+Ctrl+Alt+l	Stretch Contrast (same?)
Curves	Ctrl+m	Curves
Color Balance	Ctrl+b	Color Balance
Hue/Saturation	Ctrl+u	Hue-Saturation
Desaturate	Shift+Ctrl+u	Desaturate
Invert	Ctrl+i	Invert
Default Colors	d	Default Colors
Switch Colors	x	Switch Colors
 
Layer
PHOTOSHOP	SHORTCUT	GIMP
New Layer	Shift+Ctrl+n	New Layer
Layer via Copy	Ctrl+j	Duplicate Layer
Bring (layer) to Front	Shift+Ctrl+]	Layer to Top
Send (layer) to Back	Shift+Ctrl+[	Layer to Bottom
Bring (layer) Forward	Ctrl+]	Raise Layer
Send (layer) Backward	Ctrl+[	Lower Layer
Select Top Layer	Shift+Alt+]	Select Top Layer
Select Bottom Layer	Shift+Alt+[	Select Bottom Layer
Select One Layer Forward	Alt+]	Select Previous Layer
Select One Layer Backward	Alt+[	Select Next Layer
Merge Down	Ctrl+e	Merge Down
Merge Visible	Shift+Ctrl+e	Merge Visible
Preserve Transparency	/	Keep Transparency
Cycle Modes Forwards	Shift+=	Next Layer Mode
Cycle Modes Backwards	Shift+-	Previous Layer Mode
 
Select
PHOTOSHOP	SHORTCUT	GIMP
Select All	Ctrl+a	Select All
Deselect	Ctrl+d	Select None
Inverse	Shift+Ctrl+i	Invert
Feather	Ctrl+Alt+d	Feather
 
View
PHOTOSHOP	SHORTCUT	GIMP
Zoom In	Ctrl+=	Zoom In
Zoom Out	Ctrl+-	Zoom Out
Fit on Screen	Ctrl+0	Zoom to Fit Window
Actual Pixels	Ctrl+Alt+0	Zoom 1:1
Show/Hide Extras	Ctrl+h	Toggle Show Selection (close enough?)
Show/Hide Guides	Ctrl+'	Toggle Show Guides
Show/Hide Grid	Ctrl+Alt+'	Toggle Show Grid
Show/Hide Rulers	Ctrl+r	Toggle Show Rulers
Snap	Ctrl+;	Snap to Guides
Scroll View Up	Page Up	Scroll Page Up
Scroll View Down	Page Down	Scroll Page Down
Scroll View Left	Ctrl+Page Up	Scroll Page Left
Scroll View Right	Ctrl+Page Down	Scroll Page Right
 
Window/Dialogs
PHOTOSHOP	SHORTCUT	GIMP
?	F5	Tools Dialog
Color Tab	F6	Colors Dialog
Layers Tab	F7	Layers Dialog
Info Tab	F8	Image Information
 
Tools
PHOTOSHOP	SHORTCUT	GIMP
Rectangular Marquee Tool	m	Rect Select Tool
Elliptical Marquee Tool	Shift+m	Ellipse Select Tool
 	*This is a toggle between 'Elliptical Marquee Tool' and 'Rectangular Marquee Tool' in Photoshop	 
Move Tool	v	Move Tool
Lasso Tool	l	Free Select Tool
Magic Wand Tool	w	Fuzzy Select Tool
Crop Tool	c	Crop &amp; Resize Tool
Airbrush Tool	j	Airbrush Tool
Paintbrush Tool	b	Paintbrush Tool
Clone Stamp Tool	s	Clone Stamp Tool
Eraser Tool	e	Eraser Tool
Gradient Tool	g	Blend Tool
Paint Bucket Tool	Shift+g	Bucket Fill Tool
 	*This is a toggle between 'Paint Bucket Tool' and 'Gradient Tool' in Photoshop	 
Blur Tool	r	Convolve Tool
Dodge Tool	o	DodgeBurn Tool
Type Tool	t	Text Tool
Pen Tool	p	Bezier Select Tool
Eye Dropper Tool	i	Color Picker Tool
Zoom Tool	z	Magnify Tool
Previous Brush	,	Previous Brush
Next Brush	.	Next Brush
First Brush	Shift+&lt;	First Brush
Last Brush	Shift+&gt;	Last Brush
Decrease Brush Size	[	Decrease Brush Size
Increase Brush Size	]	Increase Brush Size
Decrease Brush Hardness	{	Decrease Brush Hardness
Increase Brush Hardness	}	Increase Brush Hardness
 
Help
PHOTOSHOP	SHORTCUT	GIMP
Help	F1	Help
Context Help	Shift+F1	Context Help
 
Misc.
PHOTOSHOP	SHORTCUT	GIMP
Last Filter	Ctrl+f	Repeat Last Filter
?	Shift+Ctrl+f	Reshow Last Filter
Preferences	Ctrl+k	Preferences
Liquify	Shift+Ctrl+x	IWarp (close enough?)
Toggle Quick Mask	q	Toggle Quick Mask


Spotlights - triangle of white opaque shape

Cutting out and/or replacing unwanted background or features - select large areas with the selection option like the Magic Wand tool (aka Color Range) or the Lasso (quick and fast) with feather 2 to soften edge or the pen tool which adds points/lines/Bézier curves (better control but slower), hold down the shift button as you click to add extra points/areas of the subject matter to remove. Increase the tolerance to cover more areas. To subtract from your selection hold down alt as you're clicking. 
* Layer masks are a better way of working than Erase they clip (black hides/hidden white visible/reveal). Clone Stamp can be simulated by   and brushes for other areas. 
* Leave the fine details like hair, fur, etc. to later with lasso and the shift key to draw a line all the way around your subject. Gradient Mapping - Inverse - Mask. i.e. Refine your selected image with edge detection and using the radius and edge options / adjuster (increase/decrease contrast) so that you will capture more fine detail from the background allowing easier removal. 
Remove fringe/halo

saving image as png rather than jpg/jpeg to keep transparency background intact.


Implemented [http://colorizer.org/ colour model representations] [http://paulbourke.net/texture_colour/colourspace/ Mathematical approach] - Photo stills are spatially 2d (h and w), but are colorimetrically 3d (r g and b, or H L S, or Y U V etc.) as well. 
* RGB - split cubed mapped color model for photos and computer graphics hardware using the light spectrum (adding and subtracting) 
* YUV - Y-Lightness U-blue/yellow V-red/cyan (similar to YPbPr and YCbCr) used in the PAL, NTSC, and SECAM composite digital TV color [http://crewofone.com/2012/chroma-subsampling-and-transcoding/#comment-7299 video]


Histograms

White balanced (neutral) if the spike happens in the same place in each channel of the RGB graphs. If not, you're not balanced. 
If you have sky you'll see the blue channel further off to the right.

RGB is best one to change colours. These elements RGB is a 3-channel format containing data for Red, Green, and Blue in your photo scale between 0 and 255. The area in a picture that appears to be brighter/whiter contains more red color as compared to the area which is relatively darker. Similarly in the green channel the area that appears to be darker contains less amount of green color as compared to the area that appears to be brighter.  Similarly in the blue channel the area appears to be darker contains less amount of blue color as compared to the area that appears to be brighter. Brightness luminance histogram also matches the green histogram more than any other color - human eye interprets green better e.g. RGB rough ratio 15/55/30%

RGBA (RGB+A, A means alpha channel) .  The alpha channel is used for &quot;alpha compositing&quot;, which can mostly be associated as &quot;opacity&quot;.  AROS deals in RGB with two digits for every color (red, green, blue), in ARGB you have two additional hex digits for the alpha channel.

The shadows are represented by the left third of the graph.  The highlights are represented by the right third.  And the midtones are, of course, in the middle.  The higher the black peaks in the graph, the more pixels are concentrated in that tonal range (total black area). 
By moving the black endpoint, which identifies the shadows (darkness) and a white light endpoint (brightness) up and down either sides of the graph, colors are adjusted based on these points. 
By dragging the central one, can increased the midtones and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .


RGB Curves

* Move left endpoint (black point) up or right endpoint (white point) up brightens 
* Move left endpoint down or right endpoint down darkens

Color Curves

* Dragging up on the Red Curve increases the intensity of the reds in the image but 
* Dragging down on the Red Curve decreases the intensity of the reds and thus increases the apparent intensity of its complimentary color, cyan. Green’s complimentary color is magenta, and blue’s is yellow.
&lt;pre&gt;
 Red &lt;-&gt; Cyan
 Green &lt;-&gt;Magenta
 Blue &lt;-&gt;Yellow 
&lt;/pre&gt;

YUV Best option to analyse and pull out statistical elements of any picture (i.e.  separate luminance data from color data). The line in Y luma tone box represents the brightness of the image with the point in the bottom left been black, and the point in the top right as white.  A low-contrast image has a concentrated clump of values nearer to the center of the graph. By comparison, a high-contrast image has a wider distribution of values across the entire width of the Histogram.   A histogram that is skewed to the right would indicate a picture that is a bit overexposed because most of the color data is on the lighter side (increase exposure with higher value F), while a histogram with the curve on the left shows a picture that is underexposed. This is good information to have when using post-processing software because it shows you not only where the color data exists for a given picture, but also where any data has been clipped (extremes on edges of either side): that is, it does not exist and, therefore, cannot be edited.  By dragging the endpoints of the line and as well as the central one, can increased the dark/shadows, midtones and light/bright parts and control the contrast, raise shadows levels, clip or softly eliminate unsafe levels, alter gamma, etc... in a way that is much more precise and creative .

The U and V chroma parts show color difference components of the image. It’s useful for checking whether or not the overall chroma is too high, and also whether it’s being limited too much
Can be used to create a negative image but also 
With U (Cb), the higher value you are, the more you're on the blue primary color. If you go to the low values then you're on blue complementary color, i.e. yellow.
With V (Cr), this is the same principle but with Red and Cyan.
e.g. If you push U full blue and V full red, you get magenta. If you push U full yellow and V full Cyan then you get green.

YUV simultaneously adds to one side of the color equation while subtracting from the other.  
using YUV to do color correction can be very problematic because each curve alters the result of each other: the mutual influence between U and V often makes things tricky. You may also be careful in what you do to avoid the raise of noise (which happens very easily). Best results are obtained with little adjustments

sunset that looks uninspiring and needs some color pop especially for the rays over the hill, a subtle contrast raise while setting luma values back to the legal range without hard clipping.


====Lunapaint====

Pixel based drawing app with onion-skin animation function

 Blocking, Shading, Coloring, adding detail 

&lt;pre&gt;
b BRUSH
e ERASER

alt eyedropper 
v layer tool 

z ZOOM / MAGNIFY &lt; &gt; n 
spc panning 
m  marque 
q lasso 
w same color selection / region 
&lt;/pre&gt;

&lt;pre&gt;
, LM RM
v 
V
f  filter 
F 
.  size 

p 
,  pick color 
[] last / next color 
&lt;/pre&gt;


There is not much missing in Lunapaint to be as good as FlipBook and then you have to take into account that Flipbook is considered to be amongst the best and easiest to use animation software out there. Ok to be honest Flipbook has some nice features that require more heavy work but those aren't so much needed right away, things like camera effects, sound, smart fill, export to different movie file formats etc.

Tried Flipbook with my tablet and compared it to Luna. The feeling is the same when sketching. LunaPaint is very responsive/fluent to draw with. Just as Flipbook is, and that responsiveness is something its users have mentioned as one of the positive sides of said software.

 author was learning MUI. Some parts just have to be rewritten with proper MUI classes before new features can be added.

* add [Frame Add] / [Frame Del]
* whole animation feature is impossible to use. If you draw 2 color maybe but if you start coloring your cells then you get in trouble
* pickup the entire image as a brush, not just a selection ? And consequently remove the brush from memory when one doesn't need it anymore. can pick up a brush and put it onto a new image but cropping isn't possible, nor to load/save brushes.
* Undo is something I longed for ages in Lunapaint.
* to import into the current layer, other types of images (e.g. JPEG) besides RAW64.
* implement graphic tablet features support


**GENERAL DRAWING**

Miss it very much:
UNDO
ERASER
COLORPICKER - has to show on palette too which color got picked.
BACKGROUND COLOR -Possibility to select from &quot;New project screen&quot;

Miss it somewhat:
ICON for UNDO
ICON for ERASER
ICON for CLEAR SCREEN ( What can I say? I start over from scratch very often )
BRUSH - possibility to cut out as brush not just copy off image to brush

**ANIMATING**

Miss it very much:
NUMBER OF CELLS - Possibity to change total no. of cells during project
ANIM BRUSH - Possibility to pick up a selected part of cells into an animbrush

Miss it somewhat:
ADD/REMOVE FRAMES: Add/remove single frame

In general LunaPaint is really well done and it feels like a new DeluxePaint version. It works with my tablet. Sure there's much missing of course but things can always be added over time. So there is great potential in LunaPaint that's for sure. Animations could be made in it and maybe put together in QuickVideo, saving in .gif or .mng etc some day.


LAYERS
-Layers names don't get saved globally in animation frames
-Layers order don't change globally in an animation (perhaps as default?).

EXPORTING IMAGES
-Exporting frames to JPG/PNG gives problems with colors. (wrong colors. See my animatiopn --&gt; My robot was blue now it's &quot;gold&quot; ) I think this only happens if you have layers.
-Trying to flatten the layers before export doesn't work if you have animation frames only the one you have visible will flatten properly all other frames are destroyed. (Only one of the layers are visible on them)
-Exporting images filenames should be for example e.g. file0001, file0002...file0010 instead as of now file1, file2...file10

LOAD/SAVE (Preferences)
-Make a setting for the default &quot;Work&quot; folder.

* Destroyed colors if exported image/frame has layers 
* mystic color cycling of the selected color while stepping frames back/forth (annoying)

&lt;pre&gt;
Deluxe Paint II enhanced key shortcuts 
    NOTE: @ denotes the ALT key

    [Technique]

    F1  - Paint
    F2  - Single Colour
    F3  - Replace
    F4  - Smear
    F5  - Shade
    F6  - Cycle
    F7  - Smooth
     M  - Colour Cycle

    [Brush]

     B  - Restore
     O  - Outline
     h  - Halve brush size
     H  - Double brush size
     x  - Flip brush on X axis
     X  - Double brush size on X axis only
     y  - Flip on Y 
     Y  - Double on Y
     z  - Rotate brush 90 degrees
     Z  - Stretch

    [Stencil]

     `  - Stencil On

    [Miscellaneous]

    F9  - Info Bar
    F10 - Selection Bar
    @o  - Co-Ordinates
    @a  - Anti-alias
    @r  - Colourise
    @t  - Translucent
    TAB - Colour Cycle

    [Picture]

     L  - Load
     S  - Save
     j  - Page to Spare(Flip)
     J  - Page to Spare(Copy)
     V  - View Page
     Q  - Quit

    [General Keys]

     m  - Magnify
     &lt;  - Zoom In
     &gt;  - Zoom Out
     [  - Palette Colour Up
     ]  - Palette Colour Down
     (  - Palette Colour Left
     )  - Palette Colour Right
     ,  - Eye Dropper
     .  - Pixel / Brush Toggle
     /  - Symmetry
     |  - Co-Ordinates
    INS - Perspective Control
    +/- - Brush Size (Fine Control)
     w  - Unfilled Polygon
     W  - Filled Polygon
     e  - Unfilled Ellipse
     E  - Filled Ellipse
     r  - Unfilled Rectangle
     R  - Filled Rectangle
     t  - Type/text tool
     a  - Select Font
    u/U - Undo
     d  - Brush
     D  - Filled Non-Uniform Polygon
    f/F - Fill Options
    g/G - Grid
    h/H - Brush Size (Coarse Control)
     K  - Clear
     c  - Unfilled Circle
     C  - Filled Circle
     v  - Line
     b  - Scissor Select and Toggle
     B  - Brush
    {,} - Toggle between two background colours
&lt;/pre&gt;

====Lodepaint====

Pixel based painting artwork app

====Grafx2====

Pixel based painting artwork app aesprite like 

[https://www.youtube.com/watch?v=59Y6OTzNrhk aesprite workflow keys and tablet use], [], 


====Vector Graphics ZuneFIG====

Vector Image Editing of files .svg .ps .eps


*Objects - raise lower rotate flip aligning snapping 
*Path - unify subtract intersect exclude divide 
*Colour - fill stroke 
*Stroke - size 
*Brushes - 
*Layers - 
*Effects - gaussian bevels glows shadows 
*Text    - 
*Transform - 


 AmiFIG ([http://epb.lbl.gov/xfig/frm_introduction.html xfig manual]) 

[[File:MyScreen.png|thumb|left|alt=Showing all Windows open in AmiFIG.|All windows available to AmiFIG.]]

for drawing simple to intermediate vector graphic images for scientific and technical uses and for illustration purposes for those with talent

;Menu options
* Load - fig format but import(s) SVG
* Save - fig format but export(s) eps, ps, pdf, svg and png
* PAN = Ctrl + Arrow keys 
* Deselect all points

There is no selected object until you apply the tool, and the selected object is not highlighted.

;Metrics - to set up page and styles - first window to open on new drawings

;Tools - Drawing Primitives - set Attributes window first before clicking any Tools button(s) 
* Shapes - circles, ellipses, arcs, splines, boxes,  polygon 
* Lines - polylines
* Text &quot;T&quot; button 
* Photos - bitmaps
* Compound - Glue, Break, Scale 
* POINTs - Move, Add, Remove 
* Objects - Move, Copy, Delete, Mirror, Rotate, Paste 
use right mouse button to stop extra lines, shapes being formed and the left mouse to select/deselect tools button(s)
* Rotate - moves in 90 degree turns centered on clicked POINT of a polygon or square

;Attributes which provide change(s) to the above primitives 
* Color
* Line Width
* Line Style
* arrowheads

;Modes 
Choose from freehand, charts, figures, magnet, etc.

;Library - allows .fig clip-art to be stored 
* compound tools to add .fig(s) together

;FIG 3.2 [http://epb.lbl.gov/xfig/fig-format.html Format] as produced by xfig version 3.2.5 
&lt;pre&gt;
Landscape
Center
Inches
Letter 
100.00
Single
-2
1200 2
4 0 0 50 -1 0 12 0.0000 4 135 1050 1050 2475 This is a test.01
&lt;/pre&gt;

# change the text alignment within the textbox. I can choose left, center, or right aligned by either changing the integer in the second column from 0 (left) to 1 or 2 (center, or right). 
# The third integer in the row specifies fontcolor. For instance, 0 is black, but blue is 1 and Green3 is 13.
# The sixth integer in the bottom row specifies fontface. 0 is Times-Roman, but 16 is Helvetica (a MATLAB default).
# The seventh number is fontsize. 12 represents a 12pt fontsize. Changing the fontsize of an item really is as easy as changing that number to 20.
# The next number is the counter-clockwise angle of the text. Notice that I have changed the angle to .7854 (pi/4 rounded to four digits=45 degrees).
# twelfth number is the position according to the standard “x-axis” in Xfig units from the left. Note that 1200 Xfig units is equivalent to once inch.
# thirteenth number is the “y-position” from the top using the same unit convention as before.

* The nested text string is what you entered into the textbox.
* The “01″ present at the end of that line in the .fig file is the closing tag. For instance, a change to \100 appends a @ symbol at the end of the period of that sentence.

; Just to note there are no layers, no 3d functions, no shading, no transparency, no animation


[[#top|...to the top]]

===Audio===


# AHI uses linear panning/balance, which means that in the center, you will get -6dB. If an app uses panning, this is what you will get. Note that apps like Audio Evolution need panning, so they will have this problem.

# When using AHI Hifi modes, mixing is done in 32-bit and sent as 32-bit data to the driver. The Envy24HT driver uses that to output at 24-bit (always).

# For the Envy24/Envy24HT, I've made 16-bit and 24-bit inputs (called Line-in 16-bit, Line-in 24-bit etc.). There is unfortunately no app that can handle 24-bit recording.


====Music Mods====

Digital module (mods) trackers are music creation software using samples and sometimes soundfonts, audio plugins (VST, AU or RTAS), MIDI.

Generally, MODs are similar to MIDI in that they contain note on/off and other sequence messages that control the mod player. Unlike (most) midi files, however, they also contain sound samples that the sequence information actually plays. MOD files can have many channels (classic amiga mods have 4, corresponding to the inbuilt sound channels), but unlike MIDI, each channel can typically play only one note at once. However, since that note might be a sample of a chord, a drumloop or other complex sound, this is not as limiting as it sounds.

Like MIDI, notes will play indefinitely if they're not instructed to end. Most trackers record this information automatically if you play your music in live. If you're using manual note entry, you can enter a note-off command with a keyboard shortcut - usually Caps Lock.

In fact when considering file size MOD is not always the best option. Even a dummy song wastes few kilobytes for nothing when a simple SID tune could be few hundreds bytes and not bigger than 64kB. AHX is another small format, AHX tunes are never larger than 64kB excluding comments.

[https://www.youtube.com/watch?v=rXXsZfwgil Protrekkr] (previously aka [w:Juan_Antonio_Arguelles_Rius|NoiseTrekkr])

If Protrekkr does not start, please check if the Unit 0 has been setup in the AHI prefs and still not, go to the directory utilities/protrekkr and double click on the Protrekkr icon

*Sample
*Note - Effect 
*Track (column) - Pattern - Order

It all starts with the Sample which is used to create Note(s) in a Track (column of a tracker) 
The Note can be changed with an Effect.  A Track of Note(s) can be collected into a Pattern (section of a song) and these can be given Order to create the whole song.

Patience (notes have to be entered one at a time) or playing the bassline on a midi controller (faster - see midi section above).  Best approach is to wait until a melody popped into your head.

*Up-tempo means the track should be reasonably fast, but not super-fast. 
*Groovy and funky imply the track should have some sort of &quot;swing&quot; feel, with plenty of syncopation or off beat emphasis and a recognizable, melodic bass line. 
*Sweet and happy mean upbeat melodies, a major key and avoiding harsh sounds.
*Moody - minor key

First, create a quick bass sound, which is basically a sine wave, but can be hand drawn for a little more variance. It could also work for the melody part, too.

This is usually a bass guitar or some kind of synthesizer bass. The bass line is often forgotten by inexperienced composers, but it plays an important role in a musical piece. Together with the rhythm section the bass line forms the groove of a song. It's the glue between the rhythm section and the melodic layer of a song.

The drums are just pink noise samples, played at different frequencies to get a slightly different sound for the kick, snare, and hihats.

Instruments that fall into the rhythm category are bass drums, snares, hi-hats, toms, cymbals, congas, tambourines, shakers, etc. Any percussive instrument can be used to form part of the rhythm section.

The lead is the instrument that plays the main melody, on top of the chords. There are many instruments that can play a lead section, like a guitar, a piano, a saxophone or a flute. The list is almost endless. There is a lot of overlap with instruments that play chords. Often in one piece an instrument serves both roles. The lead melody is often played at a higher pitch than the chords.

Listened back to what was produced so far, and a counter-melody can be imagined, which can be added with a triangle wave.

To give the ends of phrases some life, you can add a solo part with a crunchy synth. By hitting random notes in the key of G, then edited a few of them.

For the climax of the song, filled out the texture with a gentle high-pitch pad… …and a grungy bass synth.


The arrow at A points at the pattern order list. As you see, the patterns don't have to be in numerical order. This song starts with pattern &quot;00&quot;, then pattern &quot;02&quot;, then &quot;03&quot;, then &quot;01&quot;, etcetera. Patterns may be repeated throughout a song.

The B arrow points at the song title. Below it are the global BPM and speed parameters. These determine the tempo of the song, unless the tempo is altered through effect commands during the song.

The C arrow points at the list of instruments. An instrument may consist of multiple samples. Which sample will be played depends on the note. This can be set in the Instrument Editing screen. Most instruments will consist of just one sample, though. The sample list for the selected instrument can be found under arrow D.

Here's a part of the main editing screen. This is where you put in actual notes. Up to 32 channels can be used, meaning 32 sounds can play simultaneously. The first six channels of pattern &quot;03&quot; at order &quot;02&quot; are shown here. The arrow at A points at the row number. The B arrow points at the note to play, in this case a C4. The column pointed at by the C arrow tells us which instrument is associated with that note, in this case instrument #1 &quot;Kick&quot;.

The column at D is used (mainly) for volume commands. In this case it is left empty which means the instrument should play at its default volume. You can see the volume column being used in channel #6.

The E column tells us which effect to use and any parameters for that effect. In this case it holds the &quot;F&quot; effect, which is a tempo command. The &quot;04&quot; means it should play at tempo 4 (a smaller number means faster).

Base pattern

When I create a new track I start with what I call the base pattern. It is worthwhile to spend some time polishing it as a lot of the ideas in the base pattern will be copied and used in other patterns. At least, that's how I work. Every musician will have his own way of working. In &quot;Wild Bunnies&quot; the base pattern is pattern &quot;03&quot; at order &quot;02&quot;.

In the section about selecting samples I talked about the four different categories of instruments: drums, bass, chords and leads. That's also how I usually go about making the base pattern. I start by making a drum pattern, then add a bass line, place some chords and top it off with a lead. This forms the base pattern from which the rest of the song will grow.


Drums

Here's a screenshot of the first four rows of the base pattern. I usually reserve the first four channels or so for the drum instruments. Right away there are a couple of tricks shown here. In the first channel the kick, or bass drum, plays some notes. Note the alternating F04 and F02 commands. The &quot;F&quot; command alters the tempo of the song and by quickly alternating the tempo; the song will get some kind of &quot;swing&quot; feel.

In the second channel the closed hi-hat plays a fairly simple pattern. Further down in the channel, not shown here, some open hi-hat notes are added for a bit of variation.

In the third and fourth channel the snare sample plays. The &quot;8&quot; command is for panning. One note is panned hard to the left and the other hard to the right. One sample is played a semitone lower than the other. This results in a cool flanging effect. It makes the snare stand out a little more in the mix.


Bass line

There are two different instruments used for the bass line. Instrument #6 is a pretty standard synthesized bass sound. Instrument #A sounds a bit like a slap bass when used with a quick fade out. By using two different instruments the bass line sounds a bit more ”human”. The volume command is used to cut off the notes. However, it is never set to zero. Setting the volume to a very small value will result in a reverb-like effect. This makes the song sound more &quot;live&quot;.

The bass line hints at the chords that will be played and the key the song will be in. In this case the key of the song is D-major, a positive and happy key.


Chords

The D major chords that are being played here are chords stabs; short sounds with a quick decay (fade out). Two different instruments (#8 and #9) are used to form the chords. These instruments are quite similar, but have a slightly different sound, panning and volume decay. Again, the reason for this is to make the sound more human. The volume command is used on some chords to simulate a delay, to achieve more of a live feel. The chords are placed off-beat making for a funky rhythm.


Lead

Finally the lead melody is added. The other instruments are invaluable in holding the track together, but the lead melody is usually what catches people's attention.

A lot of notes and commands are used here, but it looks more complex than it is. A stepwise ascending melody plays in channel 13. Channel 14 and 15 copy this melody, but play it a few rows later at a lower volume. This creates an echo effect. A bit of panning is used on the notes to create some stereo depth. Like with the bass line, instead of cutting off notes the volume is set to low values for a reverb effect. The &quot;461&quot; effect adds a little vibrato to the note, which sounds nice on sustained notes.

Those paying close attention may notice the instrument used here for the lead melody is the same as the one used for the bass line (#6 &quot;Square&quot;), except played two or three octaves higher. This instrument is a looped square wave sample. Each type of wave has its own quirks, but the square wave (shown below) is a really versatile wave form.

Song structure

Good, catchy songs are often carefully structured into sections, some of which are repeated throughout the song with small variations.

A typical pop-song structure is: Intro - Verse - Chorus - Verse - Chorus - Bridge - Chorus.

Other single sectional song structures are

&lt;pre&gt;
Strophic or AAA Song Form - oldest story telling with refrain (often title of the song) repeated in every verse section melody 
AABA Song Form - early popular, jazz and gospel fading during the 1960s 
AB or Verse/Chorus Song Form - songwriting format of choice for modern popular music since the 1960s 
Verse/Chorus/Bridge Song Form
ABAB Song Form
ABAC Song Form
ABCD Song Form
AAB 12-Bar Song Form - three four-bar lines or sub-sections 
8-Bar Song Form
16-Bar Song Form
Hybrid / Compound Song Forms
&lt;/pre&gt;

The most common building blocks are:

#INTRODUCTION(INTRO)
#VERSE
#REFRAIN
#PRE-CHORUS / RISE / CLIMB
#CHORUS
#BRIDGE
#MIDDLE EIGHT
#SOLO / INSTRUMENTAL BREAK
#COLLISION
#CODA / OUTRO
#AD LIB (OFTEN IN CODA / OUTRO)

The chorus usually has more energy than the verse and often has a memorable melody line. As the chorus is repeated the most often during the song, it will be the part that people will remember.

The bridge often marks a change of direction in the song. It is not uncommon to change keys in the bridge, or at least to use a different chord sequence. The bridge is used to build up tension towards the big finale, the last repetition of chorus.


 Playing

RCTRL:                           Play song from row 0.

LSHIFT + RCTRL:                  Play song from current row.

RALT:                            Play pattern from row 0.

LSHIFT + RALT:                   Play pattern from current row.

Left mouse on '&gt;':               Play song from row 0.

Right mouse on '&gt;':              Play song from current row.

Left mouse on '|&gt;':              Play pattern from row 0.

Right mouse on '|&gt;':             Play pattern from current row.

Left mouse on 'Edit/Record':     Edit mode on/off.

Right mouse on 'Edit/Record':    Record mode on/off.


 Editing 


LSHIFT + ESCAPE:                 Switch large patterns view on/off

TAB:                    Go to next track

LSHIFT + TAB:                    Go to prev. track

LCTRL + TAB:                    Go to next note in track

LCTRL + LSHIFT + TAB:           Go to prev. note in track

SPACE:                           Toggle Edit mode On &amp; Off

(Also stop if the song is being played)

SHIFT SPACE:                     Toggle Record mode On &amp; Off

(Wait for a key note to be pressed

or a midi in message to be received)

DOWN ARROW:                      1 Line down

UP ARROW:                        1 Line up

LEFT ARROW:                      1 Row left

RIGHT ARROW:                     1 Row right

PREV. PAGE:                      16 Arrows Up

NEXT PAGE:                       16 Arrows Down

HOME / END:                      Top left / Bottom right of pattern

LCTRL + HOME / END:              First / last track

F5, F6, F7, F8, F9:              Jump to 0, 1/4, 2/4, 3/4, 4/4 lines of the patterns

+ - (Numeric keypad):           Next / Previous pattern

LCTRL + LEFT / RIGHT:           Next / Previous pattern

LCTRL + LALT + LEFT / RIGHT:    Next / Previous position

LALT + LEFT / RIGHT:           Next / Previous instrument

LSHIFT + M:                      Toggle mute state of the current channel

LCTRL + LSHIFT + M:             Solo the current track / Unmute all

LSHIFT + F1 to F11:              Select a tab/panel

LCTRL + 1 to 4:                 Select a copy buffer


 Tracking 

1st and 2nd keys rows:           Upper octave row

3rd and 4th keys rows:           Lower octave row

RSHIFT:                          Insert a note off

/ and * (Numeric keypad)

or F1 F2:                        -1 or +1 octave

INSERT / BACKSPACE:              Insert or Delete a line in current track

or current selected block.

LSHIFT + INSERT / BACKSPACE:     Insert or Delete a line in current pattern

DELETE (NOT BACKSPACE):          Empty a column or a selected block.


 Blocks

(Blocks can also be selected with the mouse by holding the right button and scrolling the pattern with the mouse wheel).


LCTRL + A:          Select entire current track

LCTRL + LSHIFT + A: Select entire current pattern

LALT + A:          Select entire column note in a track

LALT + LSHIFT + A: Select all notes of a track

LCTRL + X:          Cut the selected block and copy it into the block-buffer

LCTRL + C:          Copy the selected block into the block-buffer

LCTRL + V:          Paste the data from the block buffer into the pattern

LCTRL + I:          Interpolate selected data from the first to the last row of a selection

LSHIFT + ARROWS

PREV. PAGE

NEXT PAGE: Select a block

LCTRL + R:          Randomize the select columns of a selection, works similar to CTRL + I (interpolating them)

LCTRL + U:          Transpose the note of a selection to 1 seminote higher

LCTRL + D:          Transpose the note of a selection to 1 seminote lower

LCTRL + LSHIFT + U: Transpose the note of a selection to 1 seminote higher (only for the current instrument)

LCTRL + LSHIFT + D: Transpose the note of a selection to 1 seminote lower  (only for the current instrument)

LCTRL + H:          Transpose the note of a selection to 1 octave higher

LCTRL + L:          Transpose the note of a selection to 1 octave lower

LCTRL + LSHIFT + H: Transpose the note of a selection to 1 octave higher (only for the current instrument)

LCTRL + LSHIFT + L: Transpose the note of a selection to 1 octave lower (only for the current instrument)

LCTRL + W:          Save the current selection into a file


 Misc 


LALT + ENTER:     Switch between full screen / windowed mode

LALT + F4:        Exit program (Windows only)

LCTRL + S:         Save current module

LSHIFT + S:         Switch top right panel to synths list

LSHIFT + I:         Switch top right panel to instruments list


&lt;pre&gt;
C-x   xh xx xx hhhh             Volume 
B-x   xh xx xx hhhh             Jump to 
A#x  xh xx xx hhhh hhhh   Slide 
F-x    xh xx xx hhhh            Tempo 
D-x   xh xx xx hhhh             Pattern Break 
G#x  xh xx xx hhhh
&lt;/pre&gt;

h Hex 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13

d Dec 01 02 03 04 05 06 07 08 09 10  11 12 13 14 15 16 17 18 19

The Set Volume command: C. Input a note, then move the cursor to the effects command column and type a C. Play the pattern, and you shouldn't be able to hear the note you placed the C by. This is because the effect parameters are 00. Change the two zeros to a 40(Hex)/64(Dec), depending on what your tracker uses. Play back the pattern again, and the note should come in at full volume.

The Position Jump command next. This is just a B followed by the position in the playing list that you want to jump to. One thing to remember is that the playing list always starts at 0, not 1. This command is usually in Hex.

Onto the volume slide command: A. This is slightly more complex (much more if you're using a newer tracker, if you want to achieve the results here, then set slides to Amiga, not linear), due to the fact it depends on the secondary tempo. For now set a secondary tempo of 06 (you can play around later), load a long or looped sample and input a note or two. A few rows after a note type in the effect command A. For the parameters use 0F. Play back the pattern, and you should notice that when the effect kicks in, the sample drops to a very low volume very quickly. Change the effect parameters to F0, and use a low volume command on the note. Play back the pattern, and when the slide kicks in the volume of the note should increase very quickly.
This because each part of the effect parameters for command A does a different thing. The first number slides the volume up, and the second slides it down. It's not recommended that you use both a volume up and volume down at the same time, due to the fact the tracker only looks for the first number that isn't set to 0. If you specify parameters of 8F, the tracker will see the 8, ignore the F, and slide the volume up. Using a slide up and down at same time just makes you look stupid. Don't do it...

The Set Tempo command: F, is pretty easy to understand. You simply specify the BPM (in Hex) that you want to change to. One important thing to note is that values of lower than 20 (Hex) sets the secondary tempo rather than the primary.

Another useful command is the Pattern Break: D. This will stop the playing of the current pattern and skip to the next one in the playing list. By using parameters of more than 00 you can also specify which line to begin playing from.

Command 3 is Portamento to Note. This slides the currently playing note to another note, at a specified speed. The slide then stops when it reaches the desired note. 
&lt;pre&gt;
   C-2 1 000 - Starts the note playing
   ---      000
   C-3    330 - Starts the slide to C-3 at a speed of 30.
   ---     300 - Continues the slide
   ---     300 - Continues the slide
&lt;/pre&gt;
Once the parameters have been set, the command can be input again without any parameters, and it'll still perform the same function unless you change the parameters. This memory function allows certain commands to function correctly, such as command 5, which is the Portamento to Note and Volume Slide command. Once command 3 has been set up command 5 will simply take the parameters from that and perform a Portamento to Note. Any parameters set up for command 5 itself simply perform a Volume Slide identical to command A at the same time as the Portamento to Note.

This memory function will only operate in the same channel where the original parameters were set up.
There are various other commands which perform two functions at once. They will be described as we come across them.

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  00

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  02

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  05

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  08

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0A

C-3  04  ..  ..  09  00 ---&gt; C-3  04  ..  ..  09  0D

C-3  04  ..  ..  09  10 ---&gt; C-3  04  ..  ..  09  10

(You can also switch on the Slider Rec to On, and perform parameter-live-recording, such as cutoff transitions, resonance or panning tweaking, etc..)  Note: this command only works for volume/panning and fx datas columns.


The next command we'll look at is the Portamento up/down: 1 and 2. Command 1 slides the pitch up at a specified speed, and 2 slides it down. This command works in a similar way to the volume slide, in that it is dependent on the secondary tempo. Both these commands have a memory dependent on each other, if you set the slide to a speed of 3 with the 1 command, a 2 command with no parameters will use the speed of 3 from the 1 command, and vice versa.

Command 4 is Vibrato. Vibrato is basically rapid changes in pitch, just try it, and you'll see what I mean. Parameters are in the format of xy, where x is the speed of the slide, and y is the depth of the slide. One important point to remember is to keep your vibratos subtle and natural so a depth of 3 or less and a reasonably fast speed, around 8, is usually used. Setting the depth too high can make the part sound out of tune from the rest.
Following on from command 4 is command 6. This is the Vibrato and Volume Slide command, and it has a memory like command 5, which you already know how to use.

Command 7 is Tremolo. This is similar to vibrato. Rather than changing the pitch it slides the volume. The effect parameters are in exactly the same format.   vibrato effect (0x1dxy) x = speed y = depth (can't be used if arpeggio (0x1b) is turned on) 

&lt;pre&gt;
 C-7 00 .. .. 1B37 &lt;-  Turn Arpeggio effect on
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B38 &lt;- Change datas
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 0000
  --- .. .. .. 1B00 &lt;- Turn it off
&lt;/pre&gt;

Command 9 is Sample Offset. This starts the playback of the sample from a different place than the start. The effect parameters specify the sample offset, but only very roughly. Say you have a sample which is 8765(Hex) bytes long, and you wanted it to play from position 4321(Hex). The effect parameter could only be as accurate as the 43 part, and it would ignore the 21.

Command B is the Playing List/Order Jump command. The parameters specify the position in the Playing List/Order to jump to. When used in conjunction with command D you can specify the position and the line to play from.

Command E is pretty complex, as it is used for a lot of different things, depending on what the first parameter is. Let's take a trip through each effect in order.
Command E0 controls the hardware filter on an Amiga, which, as a low pass filter, cuts off the highest frequencies being played back. There are very few players and trackers on other system that simulate this function, not that you should need to use it. The second parameter, if set to 1, turns on the filter. If set to 0, the filter gets turned off.

Commands E1/E2 are Fine Portamento Up/Down. Exactly the same functions as commands 1/2, except that they only slide the pitch by a very small amount. These commands have a memory the same as 1/2 as well.

Command E3 sets the Glissando control. If parameters are set to 1 then when using command 3, any sliding will only use the notes in between the original note and the note being slid to. This produces a somewhat jumpier slide than usual. The best way to understand is to try it out for yourself. Produce a slow slide with command 3, listen to it, and then try using E31.

Command E4 is the Set Vibrato Waveform control. This command controls how the vibrato command slides the pitch. Parameters are 0 - Sine, 1 - Ramp Down (Saw), 2 - Square. By adding 4 to the parameters, the waveform will not be restarted when a new note is played e.g. 5 - Sine without restart.

Command E5 sets the Fine Tune of the instrument being played, but only for the particular note being played. It will override the default Fine Tune for the instrument. The parameters range from 0 to F, with 0 being -8 and F being +8 Fine Tune. A parameter of 8 gives no Fine Tune. If you're using a newer tracker that supports more than -8 to +8 e.g. -128 to +128, these parameters will give a rough Fine Tune, accurate to the nearest 16.

Command E6 is the Jump Loop command. You mark the beginning of the part of a pattern that you want to loop with E60, and then specify with E6x the end of the loop, where x is the number of times you want it to loop.

Command E7 is the Set Tremolo Waveform control. This has exactly the same parameters as command E4, except that it works for Tremolo rather than Vibrato.

Command E9 is for Retriggering the note quickly. The parameter specifies the interval between the retrigs. Use a value of less than the current secondary tempo, or else the note will not get retrigged.

Command EA/B are for Fine Volume Slide Up/Down. Much the same as the normal Volume Slides, except that these are easier to control since they don't depend on the secondary tempo. The parameters specify the amount to slide by e.g. if you have a sample playing at a volume of 08 (Hex) then the effect EA1 will slide this volume to 09 (Hex). A subsequent effect of EB4 would slide this volume down to 05 (Hex).

Command EC is the Note Cut. This sets the volume of the currently playing note to 0 at a specified tick. The parameters should be lower than the secondary tempo or else the effect won't work.

Command ED is the Note Delay. This should be used at the same time as a note is to be played, and the parameters will specify the number of ticks to delay playing the note. Again, keep the parameters lower than the secondary tempo, or the note won't get played!

Command EE is the Pattern Delay. This delays the pattern for the amount of time it would take to play a certain number of rows. The parameters specify how many rows to delay for.

Command EF is the Funk Repeat command. Set the sample loop to 0-1000. When EFx is used, the loop will be moved to 1000- 2000, then to 2000-3000 etc. After 9000-10000 the loop is set back to 0- 1000. The speed of the loop &quot;movement&quot; is defined by x. E is two times as slow as F, D is three times as slow as F etc. EF0 will turn the Funk Repeat off and reset the loop (to 0-1000).

effects 0x41 and 0x42 to control the volumes of the 2 303 units

There is a dedicated panel for synth parameter editing with coherent sections (osc, filter modulation, routing, so on) the interface is much nicer, much better to navigate with customizable colors, the reverb is now customizable (10 delay lines), It accepts newer types of Waves (higher bit rates, at least 24). Has a replay routine.

It's pretty much your basic VA synth. The problem isn't with the sampler being to high it's the synth is tuned two octaves too low, but if you want your samples tuned down just set the base note down 2 octaves (in the instrument panel).

so the synth is basically divided into 3 sections from left to right: oscillators/envelopes, then filter and LFO's, and in the right column you have mod routings and global settings.

for the oscillator section you have two normal oscillators (sine, saw, square, noise), the second of which is tunable, the first one tunes with the key pressed. Attached to OSC 1 is a sub-oscillator, which is a sawtooth wave tuned one octave down. The phase modulation controls the point in the duty cycle at which the oscillator starts. The ADSR envelope sliders (grouped with oscs) are for modulation envelope 1 and 2 respectively. you can use the synth as a sampler by choosing the instrument at the top.

In the filter column, the filter settings are: 1 = lowpass, 2 = highpass, 3 = off. cutoff and resonance. For the LFOs they are LFO 1 and LFO 2, the ADSR sliders in those are for the LFO itself.

For the modulation routings you have ENV 1, LFO 1 for the first slider and ENV 2, LFO 2 for the second, you can cycle through the individual routings there, and you can route each modulation source to multiple destinations of course, which is another big plus for this synth. Finally the glide time is for portamento and master volume, well, the master volume... it can go quite loud.

The sequencer is changed too, It's more like the one in AXS if you've used that, where you can mute tracks to re-use patterns with variation.


&lt;pre&gt;
Support for the following modules formats:
669 (Composer 669, Unis 669), 
AMF (DSMI Advanced Module Format), 
AMF (ASYLUM Music Format V1.0), 
APUN (APlayer), DSM (DSIK internal format), 
FAR (Farandole Composer), 
GDM (General DigiMusic), 
IT (Impulse Tracker), 
IMF (Imago Orpheus), 
MOD (15 and 31 instruments), 
MED (OctaMED), 
MTM (MultiTracker Module editor), 
OKT (Amiga Oktalyzer), 
S3M (Scream Tracker 3), 
STM (Scream Tracker), 
STX (Scream Tracker Music Interface Kit), 
ULT (UltraTracker), 
UNI (MikMod), 
XM (FastTracker 2),
Mid (midi format via timidity)
&lt;/pre&gt;


Possible plugin options include [http://lv2plug.in/ LV2],


====Midi - Musical Instrument Digital Interface====

A midi file typically contains music that plays on up to 16 channels (as per the midi standard), but many notes can simultaneously play on each channel (depending on the limit of the midi hardware playing it).

'''Timidity'''

Although usually already installed, you can uncompress the [http://www.libsdl.org/projects/SDL_mixer/ timidity.tar.gz (14MB)] into a suitable drawer like below's SYS:Extras/Audio/ 
 assign timidity: SYS:Extras/Audio/timidity
added to SYSːs/User-Startup

'''WildMidi playback'''


'''Audio Evolution 4 (2003) 4.0.23 (from 2012)'''


*Sync Menu    - CAMD Receive, Send checked 
*Options Menu - MIDI Machine Control - Midi Bar Display - Select CAMD MIDI in / out - Midi Remote Setup 


MCB Master Control Bus 
*Sending a MIDI start-command and a Song Position Pointer, you can synchronize audio with an external MIDI sequencer (like B&amp;P). 
*B&amp;P Receive, start AE, add AudioEvolution.ptool in Bars&amp;Pipes track, press play / record in AE then press play in Pipes 
*CAMD Receive, receive MIDI start or continue commands via camd.library sync to AE 


*MIDI Machine Control
*Midi Bar Display 
*Select CAMD MIDI in / out
*Midi Remote Setup - open requester for external MIDI controllers to control app mixer and transport controls cc remotely 
 Channel   - mixer(vol, pan, mute, solo), eq, aux, fx, 
 Subgroup  - Volume, Mute, Solo 
 Transport - Start, End, Play, Stop, Record, Rewind, Forward 
 Misc      - Master vol., Bank Down, Bank up 


&lt;pre&gt;
q        - quit 

First 3 already opened when AE started 
F1       - timeline window
F2       - mixer 
F3       - control 
F4       - subgroups 
F5       - aux returns 
F6       - sample list 

i        - Load sample to use 

space    - start/stop play 
b        - reset time 0:00


s        - split mode 
r        - open recording window 
a        - automation edit mode with p panning, m mute and v volume 


[ / ]    - zoom in / out 
:        - previous track
*        - next track 

x c v f  - cut copy paste cross-fade 
g        - snap grid 


&lt;/pre&gt;


 '''[http://bnp.hansfaust.de/ Bars n Pipes sequencer]'''

 BarsnPipes debug ... in shell 

Menu (right mouse)  
*Song        - Songs load and save in .song format but option here to load/save Midi_Files .mid in FORMAT0 or FORMAT1 
*Track       - 
*Edit        -
*Tool        - 
*Timing      - SMTPE Synchronizing 
*Windows     - 
*Preferences - Multiple MIDI-in option 

Windows (some of these are usually already opened when Bars n Pipes starts up for the first time) 
*Workflow -&gt; Tracks, .... Song Construction, Time-line Scoring, Media Madness, Mix Maestro, 
*Control  -&gt; Transport (or mini one), Windows (which collects all the Windows icons together-shortcut), .... Toolbox, Accessories, Metronome, 

Once you have your windows placed on the screen that suits your workflow, Song -&gt; Save as Default will save the positions, colors, icons, etc as you'd like them 

If you need a particular setup of Tracks, Tools, Tempos etc, you save them all as a new song you can load each time 

Right mouse menu -&gt; Preferences -&gt; Environment... -&gt; ScreenMode  - Linkages for Synch (to Slave) usbmidi.out.0 and Send (Master) usbmidi.in.0 - Clock MTC 


'''Tracks'''

#Double-click on B&amp;P's icon. B&amp;P will then open with an empty Song. You can also double-click on a song icon to open a song in B&amp;P.
#Choose a track. The B&amp;P screen will contain a Tracks Window with a number of tracks shown as pipelines (Track 1, Track 2, etc...). To choose a track, simply click on the gray box to show an arrow-icon to highlight it. This icon show whether a track is chosen or not. To the right of the arrow-icon, you can see the icon for the midi-input. If you double-click on this icon you can change the MIDI-in setup.
#Choose Record for the track. To the right of the MIDI-input channel icon you can see a pipe. This leads to another clickable icon with that shows either P, R or M. This stands for Play, Record or Merge. To change the icon, simply click on it. If you choose P, this track can only play the track (you can't record anything). If you choose R, you can record what you play and it overwrites old stuff in the track. If you choose M, you merge new records with old stuff in the track. Choose R now to be able to make a record.
#Chose MIDI-channel. On the most right part of the track you can see an icon with a number in it. This is the MIDI-channel selector. Here you must choose a MIDI-channel that is available on your synthesizer/keyboard. If you choose General MIDI channel 10, most synthesizer will play drum sounds. To the left of this icon is the MIDI-output icon. Double-click on this icon to change the MIDI-output configuration.
#Start recording. The next step is to start recording. You must then find the control buttons (they look like buttons on a CD-player). To be able to make a record. you must click on the R icon. You can simply now press the play button (after you have pressed the R button) and play something on you keyboard. To playback your composition, press the Play button on the control panel.
#Edit track. To edit a track, you simply double click in the middle part of a track. You will then get a new window containing the track, where you can change what you have recorded using tools provided. Take also a look in the drop-down menus for more features.


Videos to help understand [https://www.youtube.com/watch?v=A6gVTX-9900 small intro], [https://www.youtube.com/watch?v=abq_rUTiSA4&amp;t=3s Overview], [https://www.youtube.com/watch?v=ixOVutKsYQo Workplace Setup CC PC Sysex], [https://www.youtube.com/watch?v=dDnJLYPaZTs Import Song], [https://www.youtube.com/watch?v=BC3kkzPLkv4 Tempo Mapping], [https://www.youtube.com/watch?v=sd23kqMYPDs ptool Arpeggi-8], [https://www.youtube.com/watch?v=LDJq-YxgwQg  PlayMidi Song], [https://www.youtube.com/watch?v=DY9Pu5P9TaU Amiga Midi], [https://www.youtube.com/watch?v=abq_rUTiSA4 Learning Amiga bars and Pipes], 

Groups like [https://groups.io/g/barsnpipes/topics this] could help 


'''Tracks window'''

* blue &quot;1 2 3 4 5 6 7 8 Group&quot; and transport tape deck VCR-type controls
* Flags 
* [http://theproblem.alco-rhythm.com/org/bp.html Track 1, Track2, to Track 16, on each Track there are many options that can be activated] 

Each Track has a 

*Left LHS  - Click in grey box to select what Track to work on, Midi-In ptool icon should be here (5pin plug icon), and many more from the Toolbox on the Input Pipeline 
*Middle    - (P, R, M) Play, Record, Merge/Multi before the sequencer line and a blue/red/yellow (Thru Mute Play) Tap 
*Right RHS - Output pipeline, can have icons placed uopn it with the final ptool icon(s) being the 5pin icon symbol for Midi-OUT 

Clogged pipelines may need Esc pressed several times 


'''Toolbox (tools affect the chosen pipeline)'''

After opening the Toolbox window you can add extra Tools (.ptool) for the pipelines like keyboard(virtual), midimonitor, quick patch, transpose, triad, (un)quantize, feedback in/out, velocity etc
 right mouse -&gt; Toolbox menu option -&gt; Install Tool... and navigate to Tool drawer (folder) and select requried .ptool 

Accompany B tool to get some sort of rythmic accompaniment, Rythm Section and Groove Quantize are examples of other tools that make use of rythms
[https://aminet.net/search?query=bars Bars &amp; Pipes pattern format .ptrn] for drawer (folder). Load from the Menu as Track or Group 


'''Accessories (affect the whole app)''' 

Accessories -&gt; Install... and goto the Accessories drawer for .paccess like adding ARexx scripting support 


'''Song Construction'''
&lt;pre&gt;
F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Duplicator 
F5  Eraser 
F6  Toolpad 
F7  Bounding box 
F8  Lock to A-B-A 

A-B-A strip, section, edit flags, white boxes, 

&lt;/pre&gt;


Bars&amp;Pipes Professional offers three track formats; basic song tracks, linear tracks — which don't loop — and finally real‑time tracks. The difference between them is that both song and linear tracks respond to tempo changes, while real‑time tracks use absolute timing, always trigger at the same instant regardless of tempo alterations 

'''Tempo Map'''

F1  Pencil
F2  Magic Wand
F3  Hand 
F4  Eraser 
F5  Curve 
F6  Toolpad 


Compositions

Lyrics, Key, Rhythm, Time Signature 

'''Master Parameters'''

Key, Scale/Mode

'''Track Parameters'''

Dynamics 


'''Time-line Scoring'''


'''Media Madness'''


'''Mix Maestro'''


*ACCESSORIES         Allows the importation of other packages and additional modules 
*CLIPBOARD           Full cut, copy and paste operations, enabling user‑definable clips to be shared between tracks.
*INFORMATION         A complete rundown on the state of the current production and your machine.
*MASTER PARAMETERS   Enables global definition of time signatures, lyrics, scales, chords, dynamics and rhythm changes.
*MEDIA MADNESS       A complete multimedia sequencer which allows samples, stills, animation, etc 
*METRONOME           Tempo feedback via MIDI, internal Amiga audio and colour cycling — all three can be mixed and matched as required.
*MIX MAESTRO         Completely automated mixdown with control for both volume and pan. All fader alterations are memorised by the software 
*RECORD ACTIVATION   Complete specification of the data to be recorded/merged. Allows overdubbing of pitch‑bend, program changes, modulation etc
*SET FLAGS           Numeric positioning of location and edit flags in either SMPTE or musical time 
*SONG CONSTRUCTION   Large‑scale cut and paste of individual measures, verses or chorus, by means of bounding box and drag‑n‑drop mouse selections
*TEMPO MAP           Tempo change using a variety of linear and non‑linear transition curves 
*TEMPO PALETTE       Instant tempo changes courtesy of four user‑definable settings.
*TIMELINE SCORING    Sequencing of a selection of songs over a defined period — ideal for planning an entire set for a live performance.
*TOOLBOX             Selection screen for the hundreds of signal‑processing tools available 
*TRACKS              Opens the main track window to enable recording, editing and the use of tools.
*TRANSPORT           Main playback control window, which also provides access to user‑ defined flags, loop and punch‑in record modes.


Bars and Pipes Pro 2.5 is using internal 4-Byte IDs, to check which kind of data are currently processed.
Especially in all its files the IDs play an important role. The IDs are stored into the file in the same order they are laid out in the memory.

In a Bars 'N' Pipes file (no matter which kind) the ID &quot;NAME&quot; (saved as its ANSI-values) is stored on a big endian system (68k-computer) as &quot;NAME&quot;. On a little endian system (x86 PC computer) as &quot;EMAN&quot;.  The target is to make the AROS-BnP compatible to songs, which were stored on a 68k computer (AMIGA).

If possible, setting MIDI channels for Local Control for your keyboard 

http://www.fromwithin.com/liquidmidi/archive.shtml


MIDI files are essentially a stream of event data. An event can be many things, but typically &quot;note on&quot;, &quot;note off&quot;, &quot;program change&quot;, &quot;controller change&quot;, or messages that instruct a MIDI compatible synth how to play a given bit of music.

* Channel     - 1 to 16 -
* Messages    - PC presets, CC effects like delays, reverbs,  etc 
* Sequencing  - MIDI instruments, Drums, Sound design, 
* Recording   - 
* GUI         - Piano roll or Tracker, Staves and Notes 

MIDI events/messages like step entry e.g. Note On, Note Off 

MIDI events/messages like PB, PC, CC, Mono and Poly After-Touch, Sysex, etc 

MIDI sync - Midi Clocks (SPS Measures), Midi Time Code (h, m, s and frames) SMPTE 

Individual track editing with audition edits so easier to test any changes. Possible to stop track playback, mix clips from the right edit flag and scroll the display using arrow keys. 

Step entry, to extend a selected note hit the space bar and the note grows accordingly. Ability to cancel mouse‑driven edits by simply clicking the right mouse button — at which point everything snaps back into its original form. Lyrics can now be put in with syllable dividers, even across an entire measure or section. Autoranging when you open a edit window, the notes are automatically displayed — working from the lowest upwards. 

Flag editing, shift‑click on a flag immediately open the bounds window, ready for numeric input. Ability to cancel edits using the right‑hand mouse button, plus much improved Bounding Box operations.

Icons other than the BarsnPipes icon -&gt; PUBSCREEN=BarsnPipes (cannot choose modes higher than 8bit 256 colors)

Preferences -&gt; Menu in Tracks window - Send MIDI defaults OFF 

Prefs -&gt; Environment -&gt; screenmode (saved to BarsnPipes.prefs binary file) 

Customization -&gt; pics in gui drawer (folder) - 


Can save as .song files and .mid General Midi 

SMF is a “Standard Midi File”  ([http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html SMF0, SMF1 and SMF2]), [https://github.com/stump/libsmf libsmf], [https://github.com/markc/midicomp MIDIcomp], [https://github.com/MajicDesigns/MD_MIDIFile C++ src], [], [https://github.com/newdigate/midi-smf-reader Midi player], 

* SMF0        All MIDI data is stored in one track only, separated exclusively by the MIDI channel.
* SMF1        The MIDI data is stored in separate tracks/channels.
* SMF2 (rarely used) The MIDI data is stored in separate tracks, which are additionally wrapped in containers, so it's possible to have e.g. several tracks using the same MIDI channels.


Would it be possible to enrich Bars N’Pipes with software synth and sample support along with audio recording and mastering tools like in the named MAC or PC music sequencers?
On the classic AMIGA-OS this is not possible because of missing CPU-power. The hardware of the classic AMIGA is not further developed. So we must say (unfortunately) that those dreams can’t become reality

BarsnPipes is best used with external MIDI-equipment. This can be a keyboard or synthesizer with MIDI-connectors. 

&lt;pre&gt;
MIDI can control 16 channels 
There are USB-MIDI-Interfaces on the market with 16 independent MIDI-lines (multi-port), which can handle 16 MIDI devices independently – 16×16 = 256 independent MIDI-channels or instruments 
handle up to 16 different USB-MIDI-Interfaces (multi-device). That is: 16X16X16 = 4096 independent MIDI-channels – theoretically 
&lt;/pre&gt;

&lt;pre&gt;
Librarian MIDI SYStem EXplorer (sysex) - PatchEditor and used to be supplied as a separate program like PatchMeister but currently not at present 
It should support MIDI.library (PD), BlueRibbon.library (B&amp;P), TriplePlayPlus, and CAMD.library (DeluxeMusic) and 
MIDI information from a device's user manual and configure a custom interface to access parameters for all MIDI products connected to the system 
Supports ALL MIDI events and the Patch/Librarian data is stored in MIDI standard format 
Annette M.Crowling, Missing Link Software, Inc.
&lt;/pre&gt;


Composers
&lt;pre&gt;
[https://x.com/hirasawa/status/1403686519899054086 Susumu Hirasawa] 

&lt;/pre&gt;


&lt;pre&gt;
1988 Todor Fay and his wife Melissa Jordan Gray, who founded the Blue Ribbon Inc
1992 Bars&amp;Pipes Pro published 
November 2000, Todor Fay announcement to release the sourcecode of Bars&amp;Pipes Pro 2.5c beta
end of May 2001, the source of the main program and the sources of some tools and accessories were in a complete and compileable state 
end of October 2009 stop further development of BarsnPipes New for now on all supported systems and made freeware 
2013 Alfred Faust diagnosed with incureable illness, called „Myastenia gravis“ (weak muscles) 
&lt;/pre&gt;


 Protrekkr

How to use Midi In/Out in Protrekkr ?

First of all, midi in &amp; out capabilities of this program are rather limited.

# Go to Misc. Setup section and select a midi in or out device to use (ptk only supports one device at a time).
# Go to instrument section, and select a MIDI PRG (the default is N/A, which means no midi program selected).
# Go to track section and here you can assign a midi channel to each track of ptk.
# Play notes :]. Note off works. F'x' note cut command also works too, and note-volume command (speed) is supported.

Also, you can change midicontrollers in the tracker, using '90' in the panning row:

&lt;pre&gt;
    C-3 02 .. .. 0000....


    --- .. .. 90 xxyy.... &lt;&lt; This will set the value 
    --- .. .. .. 0000....    of the controller n.'xx' to 'yy' (both in hex)
    --- .. .. .. 0000....
&lt;/pre&gt;

So &quot;--- .. .. 90 2040....&quot; will set the controller number $20(32) to $40(64).

You will need the midi implementation table of your gear to know what you can change with midi controller messages.

 N.B. Not all MIDI devices are created equal!

Although the MIDI specification defines a large range of MIDI messages of various kinds, not every MIDI device is required to work in exactly the same way and respond to all the available messages and ways of working. For example, we don't expect a wind synthesiser to work in the same way as a home keyboard.

Some devices, the older ones perhaps, are only able to respond to a single channel. With some of those devices that channel can be altered from the default of 1 (probably) to another channel of the 16 possible.

Other devices, for instance monophonic synthesisers, are capable of producing just one note at a time, on one MIDI channel. Others can produce many notes spread across many channels.

Further devices can respond to, and transmit, &quot;breath controller&quot; data (MIDI controller number 2 (CC#2)) others may respond to the reception of CC#2 but not be able to create and to send it.

A controller keyboard may be capable of sending &quot;expression pedal&quot; data, but another device may not be capable of responding to that message.

Some devices just have the basic GM sound set. The &quot;voice&quot; or &quot;instrument&quot; is selected using a &quot;Program Change&quot; message on its own.

Other devices have a greater selection of voices, usually arranged in &quot;banks&quot;, and the choice of instrument is made by responding to &quot;Bank Select MSB&quot; (MIDI controller 0 (CC#0)), others use &quot;Bank Select LSB&quot; (MIDI controller number 32 (CC#32)), yet others use both MSB and LSB sent one after the other, all followed by the Program Change message. The detailed information about all the different voices will usually be available in a published MIDI Data List.


 MIDI Implementation Chart

But in the User Manual there is sometimes a summary of how the device works, in terms of MIDI, in the chart at the back of the manual, the MIDI Implementation Chart.

If you require two devices to work together you can compare the two implementation charts to see if they are &quot;compatible&quot;. In order to do this we will need to interpret that chart.

The chart is divided into four columns headed &quot;Function&quot;, &quot;Transmitted&quot; (or &quot;Tx&quot;), &quot;Received&quot; (or &quot;Rx&quot;), or more correctly &quot;Recognised&quot;, and finally, &quot;Remarks&quot;.

&lt;pre&gt;
The left hand column defines which MIDI functions are being described.
The 2nd column defines what the device in question is capable of transmitting to another device.
The 3rd column defines what the device is capable of responding to.
The 4th column is for explanations of the values contained within these previous two columns.
&lt;/pre&gt;

There should then be twelve sections, with possibly a thirteenth containing extra &quot;Notes&quot;. Finally there should be an explanation of the four MIDI &quot;modes&quot; and what the &quot;X&quot; and the &quot;O&quot; mean.
&lt;pre&gt;
Mode 1: Omni On, Poly; 
Mode 2: Omni On, Mono; 
Mode 3: Omni Off, Poly; 
Mode 4: Omni Off, Mono.
&lt;/pre&gt;
O means &quot;yes&quot; (implemented), X means &quot;no&quot; (not implemented).

Sometimes you will find a row of asterisks &quot;**************&quot;, these seem to indicate that the data is not applicable in this case. Seen in the transmitted field only (unless you've seen otherwise).

Lastly you may find against some entries an asterisk followed by a number e.g. *1, these will refer you to further information, often on a following page, giving more detail.

Basic Channel
But the very first set of boxes will tell us the &quot;Basic Channel(s)&quot; that the device sends or receives on. 
&quot;Default&quot; is what happens when the device is first turned on, &quot;changed&quot; is what a switch of some kind may allow the device to be set to. 
For many devices e.g. a GM sound module or a home keyboard, this would be 1-16 for both. That is it can handle sending and receiving on all MIDI channels.

On other devices, for example a synthesiser, it may by default only work on channel 1. But the keyboard could be &quot;split&quot; with the lower notes e.g. on channel 2. If the synth has an arppegiator, this may be able to be set to transmit and or receive on yet another channel.
So we might see the default as &quot;1&quot; but the changed as &quot;1-16&quot;.

Modes.
We need to understand Omni On and Off, and Mono and Poly, then we can decipher the four modes.

But first we need to understand that any of these four Mode messages can be sent to any MIDI channel. They don't necessarily apply to the whole device.

If we send an &quot;Omni On&quot; message (CC#125) to a MIDI channel of a device, we are, in effect, asking it to respond to e.g. a Note On / Off message pair, received on any of the sixteen channels. Sound strange? Read it again. Still strange? It certainly is. We normally want a MIDI channel to respond only to Note On / Off messages sent on that channel, not any other. In other words, &quot;Omni Off&quot;.

So &quot;Omni Off&quot; (CC#124) tells a channel of our MIDI device to respond only to messages sent on that MIDI channel.

&quot;Poly&quot; (CC#127) is for e.g. a channel of a polyphonic sound module, or a home keyboard, to be able to respond to many simultaneous Note On / Off message pairs at once and produce musical chords.

&quot;Mono&quot; (CC#126) allows us to set a channel to respond as if it were e.g. a flute or a trumpet, playing just one note at a time. If the device is capable of it, then the overlapping of notes will produce legato playing, that is the attack portion of the second note of two overlapping notes will be removed resulting in a &quot;smoother&quot; transition.

So a channel with a piano voice assigned to it will have Omni Off, Poly On (Mode 3), a channel with a saxophone voice assigned could be Omni Off, Mono On (Mode 4).

We call these combinations the four modes, 1 to 4, as defined above. 
Most modern devices will have their channels set to Mode 3 (Omni Off, Poly) but be switchable, on a per channel basis, to Mode 4 (Omni Off, Mono).

This second section of data will include first its default value i.e. upon device switch on. Then what Mode messages are acceptable, or X if none.

Finally, in the &quot;Altered&quot; field, how a Mode message that can't be implemented will be interpreted. Usually there will just be a row of asterisks effectively meaning nothing will be done if you try to switch to an unimplemented mode.

Note Number
&lt;pre&gt;
The next row will tell us which MIDI notes the device can send or receive, normally 0-127.
The second line, &quot;True Voice&quot; has the following in the MIDI specification: 
&quot;Range of received note numbers falling within the range of true notes produced by the instrument.&quot;
My interpretation is that, for instance, a MIDI piano may be capable of sending all MIDI notes (0 to 127) by transposition, but only responding to the 88 notes (21 to 108) of a real piano. 
&lt;/pre&gt;

Velocity
This will tell us whether the device we're looking at will handle note velocity, and what range from 1-127, or maybe just 64, it transmits or will recognise. So usually &quot;O&quot; plus a range or &quot;X&quot; for not implemented.

After touch
This may have one or two lines two it.
If a one liner the either &quot;O&quot; or &quot;X&quot;, yes or no.
If a two liner then it may include &quot;Keys&quot; or &quot;Poly&quot; and &quot;Channel&quot;.
This will show whether the device will respond to Polyphonic after touch or channel after touch or neither.

Pitch Bend
Again &quot;O&quot; for implemented, &quot;X&quot; for not implemented.
(Many stage pianos will have no pitch bend capability.)
It may also, in the notes section, state whether it will respond to the full 14 bits, or not, as usually encoded by the pitch bend wheel.

Control Change
This is likely to be the largest section of the chart.
It will list all those controllers, starting from CC#0, Bank Select MSB, which the device is capable of sending, and those that it will respond to using &quot;O&quot; or &quot;X&quot; respectively.
You will, almost certainly, get some further explanation of functionality in the remarks column, or in more detail elsewhere in the documentation.

Of course you will need to know what all the various controller numbers do. Lots of the official technical specifications can be found at the [www.midi.org/techspecs/ MMA], with the table of messages and control change [www.midi.org/techspecs/midimessages.php message numbers]

Program Change
Again &quot;O&quot; or &quot;X&quot; in the Transmitted or Recognised column to indicate whether or not the feature is implemented. In addition a range of numbers is shown, typically 0-127, to show what is available.
True # (number): &quot;The range of the program change numbers which correspond to the actual number of patches selected.&quot;

System Exclusive
Used to indicate whether or not the device can send or recognise System Exclusive messages. A short description is often given in the Remarks field followed by a detailed explanation elsewhere in the documentation.

System Common - These include the following:
&lt;pre&gt;
MIDI Time Code Quarter Frame messages (device synchronisation).
Song Position Pointer
Song Select
Tune Request
&lt;/pre&gt;
The section will indicate whether or not the device can send or respond to any of these messages.

System Real Time
These include the following:
&lt;pre&gt;
Timing Clock - often just written as &quot;Clock&quot;
Start
Stop
Continue
&lt;/pre&gt;
These three are usually just referred to as &quot;Commands&quot; and listed.
Again the section will indicate which, if any, of these messages the device can send or respond to.
&lt;pre&gt;
Aux. Messages
Again &quot;O&quot; or &quot;X&quot; for implemented or not.
Aux. = Auxiliary.
Active Sense = Active Sensing.
&lt;/pre&gt;
Often with an explanation of the action of the device.

Notes
The &quot;Notes&quot; section can contain any additional comments to clarify the particular implementation.

Some of the explanations have been drawn directly from the MMA MIDI 1.0 Detailed Specification.
And the detailed explanation of some of the functions will be found there, or in the General MIDI System Level 1 or General MIDI System Level 2 documents also published by the MMA.


 OFFICIAL MIDI SPECIFICATIONS

SUMMARY OF MIDI MESSAGES
Table 1 - Summary of MIDI Messages

The following table lists the major MIDI messages in numerical (binary) order (adapted from &quot;MIDI by the Numbers&quot; by D. Valenti, Electronic Musician 2/88, and updated by the MIDI Manufacturers Association.). This table is intended as an overview of MIDI, and is by no means complete.

WARNING! Details about implementing these messages can dramatically impact compatibility with other products. We strongly recommend consulting the official MIDI Specifications for additional information.

MIDI 1.0 Specification

Message Summary Channel Voice Messages [nnnn = 0-15 (MIDI Channel Number 1-16)]

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1000nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note Off event. 
This message is sent when a note is released (ended). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1001nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Note On event. 
This message is sent when a note is depressed (start). (kkkkkkk) is the key (note) number. (vvvvvvv) is the velocity.
|-
|&lt;!--Status--&gt;1010nnnn || &lt;!--Data--&gt;0kkkkkkk 0vvvvvvv || &lt;!--Description--&gt;Polyphonic Key Pressure (Aftertouch). 
This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. (kkkkkkk) is the key (note) number. (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Control Change. 
This message is sent when a controller value changes. Controllers include devices such as pedals and levers. Controller numbers 120-127 are reserved as &quot;Channel Mode Messages&quot; (below). (ccccccc) is the controller number (0-119). (vvvvvvv) is the controller value (0-127).
|-
|&lt;!--Status--&gt;1100nnnn || &lt;!--Data--&gt;0ppppppp || &lt;!--Description--&gt;Program Change. This message sent when the patch number changes. (ppppppp) is the new program number.
|-
|&lt;!--Status--&gt;1101nnnn || &lt;!--Data--&gt;0vvvvvvv || &lt;!--Description--&gt;Channel Pressure (After-touch). This message is most often sent by pressing down on the key after it &quot;bottoms out&quot;. This message is different from polyphonic after-touch. Use this message to send the single greatest pressure value (of all the current depressed keys). (vvvvvvv) is the pressure value.
|-
|&lt;!--Status--&gt;1110nnnn || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Pitch Bend Change. This message is sent to indicate a change in the pitch bender (wheel or lever, typically). The pitch bender is measured by a fourteen bit value. Center (no pitch change) is 2000H. Sensitivity is a function of the receiver, but may be set using RPN 0. (lllllll) are the least significant 7 bits. (mmmmmmm) are the most significant 7 bits.
|}

Channel Mode Messages (See also Control Change, above)

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;1011nnnn || &lt;!--Data--&gt;0ccccccc 0vvvvvvv || &lt;!--Description--&gt;Channel Mode Messages. 
This the same code as the Control Change (above), but implements Mode control and special message by using reserved controller numbers 120-127. The commands are:
*All Sound Off. When All Sound Off is received all oscillators will turn off, and their volume envelopes are set to zero as soon as possible c = 120, v = 0: All Sound Off
*Reset All Controllers. When Reset All Controllers is received, all controller values are reset to their default values. (See specific Recommended Practices for defaults) c = 121, v = x: Value must only be zero unless otherwise allowed in a specific Recommended Practice.
*Local Control. When Local Control is Off, all devices on a given channel will respond only to data received over MIDI. Played data, etc. will be ignored. Local Control On restores the functions of the normal controllers. 
c = 122, v = 0: Local Control Off
c = 122, v = 127: Local Control On
* All Notes Off. When an All Notes Off is received, all oscillators will turn off. 
c = 123, v = 0: All Notes Off (See text for description of actual mode commands.)
c = 124, v = 0: Omni Mode Off 
c = 125, v = 0: Omni Mode On 
c = 126, v = M: Mono Mode On (Poly Off) where M is the number of channels (Omni Off) or 0 (Omni On) 
c = 127, v = 0: Poly Mode On (Mono Off) (Note: These four messages also cause All Notes Off)
|}

System Common Messages

System Messages (0xF0)

The final status nybble is a “catch all” for data that doesn’t fit the other statuses. They all use the most significant nybble (4bits) of 0xF, with the least significant nybble indicating the specific category.

The messages are denoted when the MSB of the second nybble is 1. When that bit is a 0, the messages fall into two other subcategories.

System Common

If the MSB of the second second nybble (4 bits) is not set, this indicates a System Common message. Most of these are messages that include some additional data bytes.

System Common Messages
Type Status Byte   Number of Data Bytes      Usage 
&lt;pre&gt;
Time Code Quarter Frame	0xF1	1	Indicates timing using absolute time code, primarily for synthronization with video playback systems. A single location requires eight messages to send the location in an encoded hours:minutes:seconds:frames format*.
Song Position	0xF2	2	Instructs a sequencer to jump to a new position in the song. The data bytes form a 14-bit value that expresses the location as the number of sixteenth notes from the start of the song.
Song Select	0xF3	1	Instructs a sequencer to select a new song. The data byte indicates the song.
Undefined	0xF4	0	
Undefined	0xF5	0	
Tune Request	0xF6	0	Requests that the receiver retunes itself**.
&lt;/pre&gt;
*MIDI Time Code (MTC) is significantly complex. Please see the MIDI Specification
**While modern digital instruments are good at staying in tune, older analog synthesizers were prone to tuning drift. Some analog synthesizers had an automatic tuning operation that could be initiated with this command.


System Exclusive

If you’ve been keeping track, you’ll notice there are two status bytes not yet defined: 0xf0 and 0xf7. These are used by the System Exclusive message, often abbreviated at SysEx. SysEx provides a path to send arbitrary data over a MIDI connection. There is a group of predefined messages for complex data, like fine grained control of MIDI Time code machinery. SysEx is also used to send manufacturer defined data, such as patches, or even firmware updates.

System Exclusive messages are longer than other MIDI messages, and can be any length. The messages are of the following format:

0xF0, 0xID, 0xdd, ...... 0xF7
The message is bookended with distinct bytes.

It opens with the Start Of Exclusive (SOX) data byte, 0xF0.
The next one to three bytes after the start are an identifier.
Values from 0x01 to 0x7C are one-byte vendor IDs, assigned to manufacturers who were involved with MIDI at the beginning.
If the ID is 0x00, it’s a three-byte vendor ID - the next two bytes of the message are the value.
&lt;pre&gt;
ID 0x7D is a placeholder for non-commercial entities.
ID 0x7E indicates a predefined Non-realtime SysEx message.
ID 0x7F indicates a predefined Realtime SysEx message.
&lt;/pre&gt;
After the ID is the data payload, sent as a stream of bytes.
The transfer concludes with the End of Exclusive (EOX) byte, 0xF7.
The payload data must follow the guidelines for MIDI data bytes – the MSB must not be set, so only 7 bits per byte are actually usable. If the MSB is set, it falls into three possible scenarios.

An End of Exclusive byte marks the ordinary termination of the SysEx transfer.
System Real Time messages may occur within the transfer without interrupting it. The recipient should handle them independently of the SysEx transfer.
Other status bytes implicitly terminate the SysEx transfer and signal the start of new messages.
 Some inexpensive USB-to-MIDI interfaces aren’t capable of handling messages longer than four bytes.

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11110000 || &lt;!--Data--&gt;0iiiiiii [0iiiiiii 0iiiiiii]  0ddddddd  --- --- 0ddddddd 11110111 || &lt;!--Description--&gt;System Exclusive. 
This message type allows manufacturers to create their own messages (such as bulk dumps, patch parameters, and other non-spec data) and provides a mechanism for creating additional MIDI Specification messages. The Manufacturer's ID code (assigned by MMA or AMEI) is either 1 byte (0iiiiiii) or 3 bytes (0iiiiiii 0iiiiiii 0iiiiiii). Two of the 1 Byte IDs are reserved for extensions called Universal Exclusive Messages, which are not manufacturer-specific. If a device recognizes the ID code as its own (or as a supported Universal message) it will listen to the rest of the message (0ddddddd). Otherwise, the message will be ignored. (Note: Only Real-Time messages may be interleaved with a System Exclusive.)
|-
|&lt;!--Status--&gt;11110001 || &lt;!--Data--&gt;0nnndddd || &lt;!--Description--&gt;MIDI Time Code Quarter Frame.
nnn = Message Type
dddd = Values
|-
|&lt;!--Status--&gt;11110010 || &lt;!--Data--&gt;0lllllll 0mmmmmmm || &lt;!--Description--&gt;Song Position Pointer. 
This is an internal 14 bit register that holds the number of MIDI beats (1 beat= six MIDI clocks) since the start of the song. l is the LSB, m the MSB.
|-
|&lt;!--Status--&gt;11110011 || &lt;!--Data--&gt;0sssssss || &lt;!--Description--&gt;Song Select. 
The Song Select specifies which sequence or song is to be played.
|-
|&lt;!--Status--&gt;11110100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11110110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Tune Request. Upon receiving a Tune Request, all analog synthesizers should tune their oscillators.
|-
|&lt;!--Status--&gt;11110111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;End of Exclusive. Used to terminate a System Exclusive dump. 
|}


System Real-Time Messages

{| class=&quot;wikitable sortable&quot; width=&quot;90%&quot;
! width=&quot;10%&quot;  |Status D7----D0 
! width=&quot;10%&quot;  |Data Byte(s) D7----D0 
! width=&quot;20%&quot;  |Description
|-
|&lt;!--Status--&gt;11111000 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Timing Clock. Sent 24 times per quarter note when synchronization is required.
|-
|&lt;!--Status--&gt;11111001 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111010 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Start. Start the current sequence playing. (This message will be followed with Timing Clocks).
|-
|&lt;!--Status--&gt;11111011 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Continue. Continue at the point the sequence was Stopped.
|-
|&lt;!--Status--&gt;11111100 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Stop. Stop the current sequence.
|-
|&lt;!--Status--&gt;11111101 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Undefined. (Reserved)
|-
|&lt;!--Status--&gt;11111110 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Active Sensing. This message is intended to be sent repeatedly to tell the receiver that a connection is alive. Use of this message is optional. When initially received, the receiver will expect to receive another Active Sensing message each 300ms (max), and if it does not then it will assume that the connection has been terminated. At termination, the receiver will turn off all voices and return to normal (non- active sensing) operation. 
|-
|&lt;!--Status--&gt;11111111 || &lt;!--Data--&gt; || &lt;!--Description--&gt;Reset. Reset all receivers in the system to power-up status. This should be used sparingly, preferably under manual control. In particular, it should not be sent on power-up.
|}


Advanced Messages

Polyphonic Pressure (0xA0) and Channel Pressure (0xD0)

Some MIDI controllers include a feature known as Aftertouch. While a key is being held down, the player can press harder on the key. The controller measures this, and converts it into MIDI messages.

Aftertouch comes in two flavors, with two different status messages.

The first flavor is polyphonic aftertouch, where every key on the controller is capable of sending its own independent pressure information. The messages are of the following format:
&lt;pre&gt;
0xnc, 0xkk, 0xpp
n is the status (0xA)
c is the channel nybble
kk is the key number (0 to 127)
pp is the pressure value (0 to 127)
&lt;/pre&gt;
Polyphonic aftertouch is an uncommon feature, usually found on premium quality instruments, because every key requires a separate pressure sensor, plus the circuitry to read them all.

Much more commonly found is channel aftertouch. Instead of needing a discrete sensor per key, it uses a single, larger sensor to measure pressure on all of the keys as a group. The messages omit the key number, leaving a two-byte format
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xD)
c is the channel number
pp is the pressure value (0 to 127)
&lt;/pre&gt;

Pitch Bend (0xE0)

Many keyboards have a wheel or lever towards the left of the keys for pitch bend control. This control is usually spring-loaded, so it snaps back to the center of its range when released. This allows for both upward and downward bends.

Pitch Bend Wheel

The wheel sends pitch bend messages, of the format
&lt;pre&gt;
0xnc, 0xLL, 0xMM
n is the status (0xE)
c is the channel number
LL is the 7 least-significant bits of the value
MM is the 7 most-significant bits of the value
&lt;/pre&gt;
You’ll notice that the bender data is actually 14 bits long, transmitted as two 7-bit data bytes. This means that the recipient needs to reassemble those bytes using binary manipulation. 14 bits results in an overall range of 214, or 0 to 16,383. Because it defaults to the center of the range, the default value for the bender is halfway through that range, at 8192 (0x2000).

Control Change (0xB0)

In addition to pitch bend, MIDI has provisions for a wider range of expressive controls, sometimes known as continuous controllers, often abbreviated CC. These are transmitted by the remaining knobs and sliders on the keyboard controller shown below.


Continuous Controllers

These controls send the following message format:
&lt;pre&gt;
0xnc, 0xcc, 0xvv
n is the status (0xB)
c is the MIDI channel
cc is the controller number (0-127)
vv is the controller value (0-127)
&lt;/pre&gt;

Typically, the wheel next to the bender sends controller number one, assigned to modulation (or vibrato) depth. It is implemented by most instruments.

The remaining controller number assignments are another point of confusion. The MIDI specification was revised in version 2.0 to assign uses for many of the controllers. However, this implementation is not universal, and there are ranges of unassigned controllers.

On many modern MIDI devices, the controllers are assignable. On the controller keyboard shown in the photos, the various controls can be configured to transmit different controller numbers. Controller numbers can be mapped to particular parameters. Virtual synthesizers frequently allow the user to assign CCs to the on-screen controls. This is very flexible, but it might require configuration on both ends of the link and completely bypasses the assignments in the standard.


Program Change (0xC0)

Most synthesizers have patch storage memory, and can be told to change patches using the following command:
&lt;pre&gt;
0xnc, 0xpp
n is the status (0xc)
c is the channel
pp is the patch number (0-127)
&lt;/pre&gt;
This allows for 128 sounds to be selected, but modern instruments contain many more than 128 patches. Controller #0 is used as an additional layer of addressing, interpreted as a “bank select” command. Selecting a sound on such an instrument might involve two messages: a bank select controller message, then a program change.

Audio &amp; Midi are not synchronized, what I can do ?
Buy a commercial software package but there is a nasty trick to synchronize both. It's a bit hardcore but works for me:

 Simply put one line down to all midi notes on your pattern (use Insert key)
 and go to 'Misc. Setup', adjust the latency and just search a value
 that will make sound sync both audio/midi.

The stock Sin/Saw/Pulse and Rnd waveforms are too simple/common, is there a way to use something more complex/rich ?
You have to ability to redirect the waveforms of the instruments through the synth pipe by selecting the &quot;wav&quot; option for the oscillator you're using for this synth instrument, samples can be used as wavetables to replace the stock signals.


Sound banks like soundfont (sf2) or Kontakt2 are not supported at the moment


====DAW Audio Evolution 4====

Audio Evolution 4 gives you unsurpassed power for digital audio recording and editing on the Amiga. The latest release focusses on time-saving non-linear and non-destructive editing, as seen on other platforms. Besides editing, Audio Evolution 4 offers a wide range of realtime effects, including compression, noise gate, delays, reverb, chorus and 3-band EQ.

Whether you put them as inserts on a channel or use them as auxillaries, the effect parameters are realtime adjustable and can be fully automated. Together with all other mixing parameters, they can even be controlled remotely, using more ergonomic MIDI hardware.

Non-linear editing on the time line, including cut, copy, paste, move, split, trim and crossfade actions

The number of tracks per project(s) is unlimited .... AHI limits you to recording only two at a time. i.e. not on 8 track sound cards like the Juli@ or Phase 88.

sample file import is limited to 16bit AIFF (not AIFC, important distinction as some files from other sources can be AIFC with aiff file extention). and 16bit WAV (pcm only)


Most apps use the Music Unit only but a few apps also use Unit (0-3) instead or as well. 
* Set up AHI prefs so that microphone is available. (Input option near the bottom)


stereo++ allows the audio piece to be placed anywhere and the left-right adjusted to sound positionally right

hifi best for music playback if driver supports this option


Load 16bit .aif .aiff only sample(s) to use not AIFC which can have the same ending. AIFF stands for Audio Interchange File Format 

 sox recital.wav recital.aiff

 sox recital.wav −b 16 recital.aiff channels 1 rate 16k fade 3 norm
 sox input.wav        output.aiff bass −b 16 rate 48k

performs the same format translation, but also applies four effects (down-mix to one channel, sample rate change, fade-in, nomalize), and stores the result at a bit-depth of 16.

 rec −c 2 radio.aiff trim 0 30:00

records half an hour of stereo audio 

 play existing-file.wav


24bit PCM WAV or AIFF do not work 

*No stream format handling. So no way to pass on an AC3 encoded stream unmodified to the digital outputs through AHI.
*No master volume handling. Each application has to set its own volume. So each driver implements its own custom driver-mixer interface for handling master volumes, mute and preamps.
*Only one output stream. So all input gets mixed into one output.
*No automatic handling of output direction based on connected cables.
*No monitor input selection. Only monitor volume control. 


select the correct input (Don't mistake enabled sound for the correct input.)
The monitor will feedback audio to the lineout and hp out no matter if you have selected the correct input to the ADC. The monitor will provide sound for any valid input. This will result in free mixing when recording from the monitor input instead of mic/line because the monitor itself will provide the hardware mixing for you. Be aware that MIC inputs will give two channel mono. Only Linein will give real stereo.

Now for the not working part. Attempt to record from linein in the AE4 record window, the right channel is noise and the left channel is distorted. Even with the recommended HIFI 16bit Stereo++ mode at 48kHz.


Channels

Monitor

Gain

Inout

Output

Advanced settings - Debugging via serial port


* Options -&gt; Soundcard In/Out
* Options -&gt; SampleRate
* Options -&gt; Preferences

F6 for Sample File List

Setting a grid is easy as is measuring the BPM by marking a section of the sample. Is your kick drum track &quot;not in time&quot; ? If so, you're stumped in AE4 as it has no fancy variable time signatures and definitely no 'track this dodgy rhythm' function like software of the nature of Logic has. So if your drum beat is freeform you will need to work in freeform mode. (Real music is free form anyway).

If the drum *is* accurate and you are just having trouble measuring the time, I usually measure over a range of bars and set the number of beats in range to say 16 as this is more accurate, Then you will need to shift the drum track to match your grid *before* applying the grid. (probably an iterative process as when the grid is active samples snap to it, and when inactive you cannot see it).

AE4 does have ARexx but the functions are more for adding samples at set offsets and starting playback / recording.


These are the usual features found in DAWs...

* Recording digital audio, midi sequencer and mixer 
* virtual VST instruments and plug-ins 
* automation, group channels, MIDI channels, FX sends and returns, audio and MIDI editors and music notation editor


* different track views 
* mixer and track layout (but not the same as below) 
* traditional two windows (track and mixer)


Mixing - mixdown

Could not figure out how to select what part I wanted to send to the aux, set it to echo and return. Pretty much the whole echo effect. Or any effect.

Take look at page17 of the manual.

When you open the EQ / Aux send popup window you will see 4 sends. Now from the menu choose the windows menu.

Menus-&gt;Windows-&gt; Aux Returns Window

or press F5

You will see a small window with 4 volume controls and an effects button for each. Click a button and add an effects to that aux channel, then set it up as desired (note the reverb effect has a special AUX setting that improves its use with the aux channel, not compulsory but highly useful). You set the amount of 'return' on the main mix in the Aux Return window, and the amount sent from each main mixer channel in the popup for that channel. Again the aux sends are &quot;prefade&quot; so the volume faders on each channel do not affect them.


Tracking


Effects - fade in

To add some echoes to some vocals, tried to add an effect on a track but did not come out. This is made more complicated as I wanted to mute a vocal but then make it echo at the muting point. Want to have one word of a vocal heard and then echoed off. But when the track is mute the echo is cancelled out.

To correctly understand what is happening here you need to study the figure at the bottom of page 15 on the manual. You will see from that that the effects are applied 'prefade' So the automation you applied will naturally mute the entire signal.

There would be a number of ways to achieve the goal,

You have three real time effects slots, one for smoothing like so

Sample -&gt; Amplify -&gt; Delay

Then automate the gain of the amplify block so that it effectively mutes the sample just before the delay at the appropriate moment, the echo effect should then be heard.

Getting the effects in the right order will require experimentation as they can only be added top down and it's not obvious which order they are applied to the signal, but there only two possibilities, so it wont take long to find out.

Using MUTE can cause clicks to the Amplify can be used to mute more smoothly so that's a secondary advantage.

Signal Processing -


Overdub

[[#top|...to the top]]

===Office===

====Spreadsheet Leu====

Support for some xlsx, and ods functions 


====Spreadsheet Ignition====

; Needs ABIv1 to be completed before more can be done

File formats supported 
* ascii #?.txt and #?.csv (single sheets with data only). 
* igs and TurboCalc(WIP) #?.tc for all sheets with data, formats and formulas.

There is '''no''' support for xls, xlsx, ods or uos ([http://en.wikipedia.org/wiki/Uniform_Office_Format Uniform Unified Office Format]) at the moment.

* Always use Esc key after editing Spreadsheet cells.
* copy/paste seems to copy the first instance only so go to Edit -&gt; Clipboard to manage the list of remembered actions. 
* Right mouse click on row (1 or 2 or 3) or column header (a or b or c)  to access optimal height or width of the row or column respectively 
* Edit -&gt; Insert -&gt; Row  seems to clear the spreadsheet or clears the rows after the inserted row until undo restores as it should be...

Change Sheet name by  Object -&gt; Sheet -&gt; Properties

Click in the cell which will contain the result, and click '''down arrow button''' to the right of the formula box at the bottom of the spreadsheet and choose the function required from the list provided. Then click on the start cell and click on the bottom right corner, a '''very''' small blob, which allows stretching a bounding box (thick grey outlines) across many cells This grey bounding box can be used to '''copy a formula''' to other cells.

Object -&gt; Cell -&gt; Properties to change cell format - Currency only covers DM and not $, Euro, Renminbi, Yen or Pound etc. 
Shift key and arrow keys selects a range of cells, so that '''formatting can be done to all highlighted cells'''. 
View -&gt; Overview then select ALL with one click (in empty cell in the top left hand corner of the sheet).

Default mode is relative cell referencing e.g. a1+a2 but absolute e.g. $a$1+$a$2 can be entered.

* #sheet-name to '''absolute''' reference another sheet-name cell unless reference() function used.

;Graphs

use shift key and arrow keys to select a bunch of cells to be graph'ed making sure that x axes represents and y axes represents

* value() - 0 value, 1 percent, 2 date, 3 time, 4 unit ...


;Dates 
* Excel starts a running count from the 1st Jan 1900 and Ignition starts from 1st Jan 1AD '''(maybe this needs to change)'''
Set formatting Object -&gt; Cell -&gt; Properties and put date in days


;Time 
Set formatting Object -&gt; Cell -&gt; Properties and put time in seconds taken


;Database (to be done by someone else)

type - standard, reference (bezug), search criterion (suchkriterium), 
* select a bunch of cells and Object -&gt; Database -&gt; Define to set Datenbank (database) and Felder (fields not sure how?) 
* Neu (new) or loschen (delete) to add/remove database headings e.g. Personal, Start Date, Finish Date (one per row?)
* Object -&gt; Database -&gt; Index to add fields (felder) like Surname, First Name, Employee ID, etc. to ?

Filtering done with dbfilter(), dbproduct() and dbposition().

Activities with dbsum(), dbaverage(), dbmin() and dbmax().

Table sorting -


;Scripts (Arexx)

;Excel(TM) to Ignition - commas ''',''' replaced by semi-colons ''';''' to separate values within functions 
*SUM(), 
*AVERAGE(), MAX(), MIN(), INT(), PRODUCT(), MEDIAN(), VAR() becomes Variance(), Percentile(),
*IF(), AND, OR, NOT 
*LEFT(), RIGHT(), MID() becomes MIDDLE(), LEN() becomes LENGTH(), 
*LOWER() becomes LOWERCASE(), UPPER() becomes UPPERCASE(),
* DATE(yyyy,mm,dd) becomes COMPUTEDATE(dd;mm;yyyy), 
*TODAY(), DAY(),WEEK(), MONTH(),=YEAR(TODAY()), 
*EOMONTH() becomes MONTHLENGTH(), 
*NOW() should be date and time becomes time only, SECOND(), MINUTE(), HOUR(),
*DBSUM() becomes DSUM(),


;Missing and possibly useful features/functions needed for ignition to have better support of Excel files 
There is no Merge and Join Text over many cells, no protect and/or freeze row or columns or books but can LOCK sheets, no define bunch of cells as a name, Macros (Arexx?), conditional formatting, no Solver, no Goal Seek, no Format Painter, no AutoFill, no AutoSum function button, no pivot tables, (30 argument limit applies to Excel)

*HLOOKUP(), VLOOKUP(), [http://production-scheduling.com/excel-index-function-most-useful/ INDEX(), MATCH()], CHOOSE(), TEXT(), 
*TRIM(), FIND(), SUBSTITUTE(), CONCATENATE() or &amp;, PROPER(), REPT(), 
*[https://acingexcel.com/excel-sumproduct-function/ SUMPRODUCT()], ROUND(), ROUNDUP(), *ROUNDDOWN(), COUNT(), COUNTA(), SUMIF(), COUNTIF(), COUNTBLANK(), TRUNC(), 
*PMT(), PV(), FV(), POWER(), SQRT(), MODE(), TRUE, FALSE, 
*MODE(), LARGE(), SMALL(), RANK(), STDEV(), 
*DCOUNT(), DCOUNTA(), WEEKDAY(),


;Excel Keyboard [http://dmcritchie.mvps.org/excel/shortx2k.htm shortcuts needed to aid usability in Ignition] 
&lt;pre&gt;
Ctrl Z - Undo

Ctrl D - Fill Down
Ctrl R - Fill right

Ctrl F - Find
Ctrl H - Replace

Ctrl 1 - Formatting of Cells
CTRL SHIFT ~ Apply General Formatting ie a number 
Ctrl ; - Todays Date 

F2 - Edit cell
F4 - toggle cell absolute / relative cell references

&lt;/pre&gt;


====Document Scanning - Scandal====

Scanner usually needs to be connected via a USB port and not via a hub or extension lead.

Check in Trident Prefs -&gt; Devices that the USB Scanner is not bound to anything (e.g. Bindings None)
If not found then reboot the computer and recheck.

Start Scandal, choose Settings from Menu strip at top of screen and in Scanner Driver choose the ?#.device of the scanner (e.g. epson2.device).

The next two boxes - leave empty as they are for morphos SCSI use only
 or put ata.device (use the selection option in bigger box below) and Unit as 0 this is needed for gt68xx

* gt68xx - no editing needed in s/gt68xx.conf but needs a firmware file that corresponds to the scanner [http://www.meier-geinitz.de/sane/gt68xx-backend/ gt68xx firmwares] in sys:s/gt68xx.
* epson2 - Need to edit the file epson2.conf in sys/s that corresponds to the scanner being used

'''Save''' the settings but do not press the Use button (aros freezes)

Back to the Picture Scan window and the right-hand sections.

Click on the '''Information''' tab and press Connect button and the scanner should now be detected.

Go next to the '''Scanner''' tab next to Information Tab should have Color, Black and White, etc. and dpi settings now. Selecting an option Color, B/W etc. can cause dpi settings corruption (especially if the settings are in one line) so set '''dpi first'''. Make sure if Preview is set or not.

In the '''Scan''' Tab, press Scan and the scanner will do its duty. 
Be aware that nothing is saved to disk yet.

In the Save tab, change format JPEG, PNG or IFF DEEP. Tick incremental and base filename if necessary and then click the Save button. The image will now be saved to permanent storage.


The driver ignores a device if it is already bond to another USB class, rejects it from being usable. However, open Trident prefs, select your device and use the right mouse button to open. Select &quot;NONE&quot; to prevent poseidon from touching the device. Now save settings. It should always work now.

[[#top|...to the top]]

===Emulators===

==== Amiberry ====


==== Amiga Emu - Janus UAE ====

With Amibridge, AROS attempts to make the UAE emulator seem embedded within but it still is acting as an app 

There is no dynarec m68k for each hardware that Aros supports or direct patching of motorola calls to AROS hardware accelerated ones unless the emulator has that included 

Try starting Janus with a priority of -1 like this little script:
&lt;pre&gt;
cd sys:system/AmiBridge/emulator
changetaskpri -1
run janus-uae -f my_uaerc.config &gt;nil:
cd sys:prefs
endcli
&lt;/pre&gt;
This stops Janus hogging all the CPU time.


===Miscellaneous===

====Screensaver Blanker====

Most blankers on the amiga (i.e. aros) run as commodities (they are in the tools/commodities drawer). Double click on blanker.

Control is with an app called Exchange, which you need to run first (double click on app) or  run QUIET sys:tools/commodities/Exchange &gt;NIL: but subsequently can use (Cntrl Alt h).

Icon tool types (may be broken) or command line options 
&lt;pre&gt;
seconds=number 
&lt;/pre&gt;

Once the timing is right then add the following to s:icaros-sequence or s:user-startup

e.g. for 5 minutes

 run QUIET sys:tools/commodities/Blanker seconds=300 &gt;NIL:


*[http://archives.aros-exec.org/index.php?function=showfile&amp;file=graphics/screenblanker/gblanker.i386-aros.zip Garshneblanker] can make Aros unstable or slow. Certain blankers crashes in Icaros 2.0.x like Dragon, Executor.


*[ Acuario AROS version], the aquarium screen saver.

Startup: extras:acuariofv-aros/acuario

Kill: c:break name=extras:acuariofv-aros/acuario

Managed to start Acuario by the Executor blanker.

&lt;pre&gt;
cx_priority=
cx_popkey=    ie CX_POPKEY=&quot;Shift F1&quot; 
cx_popup=Yes or No

&lt;/pre&gt;


&lt;pre&gt;
 Qualifier String    Input Event Class
   ----------------    -----------------
    &quot;lshift&quot;           IEQUALIFIER_LSHIFT
    &quot;rshift&quot;           IEQUALIFIER_RSHIFT
    &quot;capslock&quot;         IEQUALIFIER_CAPSLOCK
    &quot;control&quot;          IEQUALIFIER_CONTROL
    &quot;lalt&quot;             IEQUALIFIER_LALT
    &quot;ralt&quot;             IEQUALIFIER_RALT
    &quot;lcommand&quot;         IEQUALIFIER_LCOMMAND
    &quot;rcommand&quot;         IEQUALIFIER_RCOMMAND
    &quot;numericpad&quot;       IEQUALIFIER_NUMERICPAD
    &quot;repeat&quot;           IEQUALIFIER_REPEAT
    &quot;midbutton&quot;        IEQUALIFIER_MIDBUTTON
    &quot;rbutton&quot;          IEQUALIFIER_RBUTTON
    &quot;leftbutton&quot;       IEQUALIFIER_LEFTBUTTON
    &quot;relativemouse&quot;    IEQUALIFIER_RELATIVEMOUSE
&lt;/pre&gt;


&lt;pre&gt;
    Synonym     Synonym
    String     Identifier
    -------    ----------
    &quot;shift&quot;    IXSYM_SHIFT    /* look for either shift key */
    &quot;caps&quot;     IXSYM_CAPS     /* look for either shift key or capslock */
    &quot;alt&quot;      IXSYM_ALT      /* look for either alt key */

Highmap is one of the following strings:
    &quot;space&quot;, &quot;backspace&quot;, &quot;tab&quot;, &quot;enter&quot;, &quot;return&quot;, &quot;esc&quot;, &quot;del&quot;,
    &quot;up&quot;, &quot;down&quot;, &quot;right&quot;, &quot;left&quot;, &quot;f1&quot;, &quot;f2&quot;, &quot;f3&quot;, &quot;f4&quot;, &quot;f5&quot;,
    &quot;f6&quot;, &quot;f7&quot;, &quot;f8&quot;, &quot;f9&quot;, &quot;f10&quot;, &quot;help&quot;.


&lt;/pre&gt;


[[#top|...to the top]]

==== World Construction Set WCS (Version 2.031) ====

WCS is a fractal landscape software such as Scenery Animator, Vista Pro and Panorama. Open sourced February 2022, World Construction Set [https://3dnature.com/downloads/legacy-software/ legally and for free] and [https://github.com/AlphaPixel/3DNature c source]. 

Announced August 1994 this version dates from April 1996 developed by Gary R. Huber and Chris &quot;Xenon&quot; Hanson&quot; from Questar 

&lt;pre&gt;
Assign &quot;WCSProjects:&quot; &quot;Volume:Dir/Dir/WCSProjects&quot; 
Assign &quot;WCSFrames:&quot;   &quot;Volume:Dir/Dir/WCSFrames&quot; 
&lt;/pre&gt;

&lt;pre&gt;
Load projects .proj by accessing pull down menu Project -&gt; Open then click on CanyonSunset.proj
OK to changing .par file and enlarge Status Log window to show what is happening 
Render by pull down menu Modules -&gt; Render with End equal 1 not 300 then click bottom middle button Render 
&lt;/pre&gt;

[https://www.youtube.com/watch?v=CxQDmf1ZWG0 Youtube walkthrough of above], [], [], 

Also try working with the already built file ColoDemo - Then open with the drop-down menu: Project/Open, then WCSProject:ColoDemo.proj
Which allows you to use altimetric DEM files already included and Loading scene parameters from ColoDemo.par
Once this is done, save everything with a new name to start working exclusively on your project. 
Then drop-down menu and select Save As (&quot;NewName&quot;.proj name), then drop-down menu to open parameter and select Save All ( .par name)


After launching the software, there is a the Module Control Panel composed of five icons. 
It is a dock type shortcut of the first few functions of the drop-down menu 

*Database   - Load (#?.proj), Append, Create, Edit, Save, Dir List (of WCSProject drawer), 
*Data Ops   - Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats  
*Map View   - Database file Loader leading to Map View Control with option to the Database Editor 
*Parameters - Editor for Motion, Color, Ecosystem, Clouds, Waves, management of altimeter files DEM, sclock settings etc 
*Render     - rendering terrain 

These are more in the pull down menu but not in the dock 
*Motion Editor
*Color Editor
*Ecosys Editor 


Simple minimal workflow 
*Load database (1st icon - 1st)
*Set parameters and save .par file (4th icon)
*Render scene (5th icon) 

[https://www.youtube.com/watch?v=ZbTwwR2qcc4 Youtube], [], 

&lt;pre&gt;
.proj new project name which creates a drawer of additional files 

.binary array, ascii array .xyz , z buffer, DTED .dt0, vista 1990s dem, iff  conversion 
.Obj with .elev, .frd with .hdr maps, - digital elevation model (DEM) is a 3D representation of elevation data in various formats 
USGS 7.5MinDEM, 

.par 


&lt;/pre&gt;


Since for the time being no project is loaded, a query window indicates a procedural error when clicking on the rendering icon (right end of the bar). The menu is quite traditional; it varies according to the activity of the windows. To display any altimetric file in the &quot;Mapview&quot; (third icon of the panel), There are three possibilities:

* Loading of a demonstration project.
* The import of a DEM file, followed by texturing and packaging from the &quot;Database-Editor&quot; and the &quot;Color-Editor&quot;.
* The creation of an altimetric file in WCS format, then texturing.


The altimeter file editing (display in the menu) is only made possible if the &quot;Mapview&quot; window is active.

The software is made up of many windows and won't be able to describe them all. Know that &quot;Color-Editor&quot; and the &quot;Data-Editor&quot; comprise sufficient functions for obtaining an almost real rendering quality. You have the possibility of inserting vector objects in the &quot;Data-Editor&quot; (creation of roads, railways, etc.) 


The Map View (MapView) window

*Database - Objects and Topos
*View     - Align, Center, Zoom, Pan, Move 
*Draw     - Maps and distance 
*Object   - Find, highlight, add points, conform topo, duplicate 
*Motion   - Camera, Focus, path, elevation 
*Windows  - DEM designer, Cloud (.cld) and wave (.wve) editor, 


You will notice that by selecting this window and simply moving the pointer to various points on the map you will see latitude and longitude values ​​change, along with the height.
Drop-down menu and Modules, then select MapView and change the width of the window with the map to arrange it in the best way on the screen. With the Auto button the center. Window that then displays the contents of my DEM file, in this case the Grand Canyon. MapView allows you to observe the shape of the landscape from above
 

ZOOM button

Press the Zoom button and then with the pointer position on a point on the map, press the left mouse button and then move to the opposite corner to circumscribe the chosen area and press the left mouse button again, then we will see the enlarged area selected on the map.
Would add that there is a box next to the Zoom button that allows the direct insertion of a value which, the larger it is, the smaller the magnification and the smaller the value, the stronger the magnification. At each numerical change you will need to press the DRAW button to update the view.

PAN button

Under Zoom you will find the PAN button which allows you to move the map at will in all directions by the amount you want. This is done by drawing a line in one direction, then press PAN and point to an area on the map with the pointer and press the left mouse button. At this point, leave it and move the pointer in one direction by drawing a line and press the left mouse button again to trigger the movement of the map on the screen (origin and end points). Do some experiments and then use the Auto button immediately below to recenter everything.
There are parameters such as TOPO, VEC to be left checked and immediately below one that allows different views of the map with the Style command (Single, Multi, Surface, Emboss, Slope, Contour), each with its own particularities to highlight different details.

Now you have the first basics to manage your project visually on the map. Close the MapView window and go further...


Let's start working on ECOSYSTEMS
If we select Emboss from the MapView Style command we will have a clear idea of ​​how the landscape appears, realizing that it is a predominantly desert region of our planet. Therefore we will begin to act on any vegetation present and the appearance of the landscape.
With WCS we will begin to break down the elements of the landscape by assigning defined characteristics. It will be necessary to determine the classes of the ecosystem (Class) with parameters of Elevation Line (maximum altitude), Relative Elevation (arrangement on basins or convexities with respectively positive or negative parameters), Min Slope and Max Slope (slope). WCS offers the possibility of making ecosystems coexist on the same terrain with the UnderEco function, by setting a Density value.


Ecosys Ecosystem Editor

Let's open it from Modules, then Ecosys Editor. In the left pane you will find the list of ecosystems referring to the files present in our project. It will be necessary to clean up that box to leave only the Water and Snow landscapes and a few other predefined ones. We can do this by selecting the items and pressing the Remove button (be careful not for all elements the button is activated, therefore they cannot all be eliminated).
Once this is done we can start adding new ecosystems. Scroll through the various Unused and as soon as the Name item at the top is activated allowing you to write, type the name of your ecosystem, adding the necessary parameters.
&lt;pre&gt;
Ecosystem1: Name: RockBase Class: Rock Density: 80 MinSlope: 15 UnderEco: Terrain
Ecosystem2: Name: RockIncl Clss: Rock Density: 80 MinSlope: 30 UnderEco: Terrain
Ecosystem3: Name: Grass Class Low Veg Density: 50 Height: 1 Elev Line : 1500 Rel El Eff: 5
Max Slope: 10 – Min Slope: 0 UnderEco: Terrain
Ecosistema4: Name: Shrubs Class: Low Veg Density: 40 Height: 8 Elev Line: 3000
Rel El Eff: -2 Max Slope: 20 Min Slope : 5 UnderEco: Terrain
Ecosistema5: Name: Terrain Class: Ground Density: 100 UnderEco: Terrain
&lt;/pre&gt;

Now we need to identify an intermediate ecosystem that guarantees a smooth transition between all, therefore we select as Understory Ecosystem the one called Terrain in all ecosystems, except Snow and Water .
Now we need to 'emerge' the Colorado River in the Canyon and we can do this by raising the sea level to 900 (Sea Level) in the Ecosystem called Water.
Please note that the order of the ecosystem list gives priority to those that come after. So our list must have the following order: Water, Snow, Shrubs, RockIncl, RockBase, Terrain. It is possible to carry out all movements with the Swap button at the bottom. To put order you can also press Short List. Press Keep to confirm all the work done so far with Ecosystem Editor.
Remember every now and then to save both the Project 'Modules/Save' and 'Parameter/Save All'

EcoModels are made up of .etp .fgp .iff8 for each model 


Color Editor

Now it's time to define the colors of our scene and we can do this by going to Modules and then Color Editor. In the list we focus on our ecosystems, created first.
Let's go to the bottom of the list and select the first white space, assigning the name 'empty1', with a color we like and then we will find this element again in other environments... It could serve as an example for other situations!
So we move to 'grass' which already exists and assign the following colors: R 60 G 70 B50
&lt;pre&gt;
'shrubs': R 60 G 80 B 30
'RockIncl' R 110 G 65 B 60
'RockBase' R 110 G 80 B 80
' Terrain' R 150 G 30 B 30
&lt;pre&gt;
Now we can work on pre-existing colors
&lt;pre&gt;
'SunLight' R 150 G 130 B 130
'Haze and Fog' R 190 G 170 B 170
'Horizon' R 209 G 185 B 190
'Zenith' R 140 G 150 B 200
'Water' R 90 G 125 B 170
&lt;/pre&gt;

Ambient R 0 G 0 B 0

So don't forget to close Color Editor by pressing Keep.
Go once again to Ecosystem Editor and assign the corresponding color to each environment by selecting it using the Ecosystem Color button. Press it several times until the correct one appears. Then save the project and parameters again, as done previously.


Motion Editor

Now it's time to take care of the framing, so let's go to Modules and then to Motion Editor. An extremely feature-rich window will open. Following is the list of parameters regarding the Camera, position and other characteristics:
&lt;pre&gt;
-Camera Altitude: 7.0
-Camera Latitude: 36.075
-Camera Longitude: 112.133
-Focus Attitude: -2.0
-Focus Latitude: 36.275
-Focus Longitude: 112.386
-Camera : 512 → rendering window
-Camera Y: 384 → rendering window
-View Arc: 80 → View width in degrees
-Sun Longitude: 172
-Sun Latitude: -0.9
-Haze Start: 3.8
-Haze Range: 78, 5
&lt;/pre&gt;
As soon as the values ​​shown in the relevant sliders have been modified, we will be ready to open the CamView window to observe the wireframe preview. Let's not consider all the controls that will appear.
Well from the Motion Editor if you have selected Camera Altitude and open the CamView panel, you can change the height of the camera by holding down the right mouse button and moving the mouse up and down. To update the view, press the Terrain button in the adjacent window. As soon as you are convinced of the position, confirm again with Keep. You can carry out the same work with the other functions of the camera, such as Focus Altitude...
Let's now see the next positioning step on the Camera map, but let's leave the CamView preview window open while we go to Modules to open the window at the same time MapView. We will thus be able to take advantage of the view from the other together with a subjective one.


From the MapView window, select with the left mouse button and while it is pressed, move the Camera as desired. To update the subjective preview, always click on Terrain.
While with the same procedure you can intervene on the direction of the camera lens, by selecting the cross and with the left button pressed you can choose the desired view. So with the pressure of Terrain I update the Preview. Possibly can enlarge or reduce the Map View using the Zoom button, for greater precision.
Also write that the circle around the cameras indicates the beginning of the haze, there are two types (haze and fog) linked to the altitude. Would also add that the camera height is editable through the Motion Editor panel.


The sun

Let's see that changing the position of the sun from the Motion Editor. Press the SUN button at the bottom right and set the time and the date. Longitude and latitude are automatically obtained by the program. Always open the View Arc command from the Motion Editor panel, an item present in the Parameter List box.

Once again confirm everything with Keep and then save again.


Animation

The animation part is not left-back and also occupies a window. The settings possibilities are enormous. A time line with dragging functions (&quot;slide&quot;, &quot;drag&quot;...) comparable to that of LightWave completes this window. 


A small window is available for positioning the stars as a function of a date, in order to vary the seasons and their various events (and yes...).

At the bottom of the &quot;Motion-Editor&quot;, a &quot;cam-view&quot; function will give you access to a control panel. Different preview modes are possible. The rendering is also accessible through a window. No less than nine pages compose it. At this level, you will be able to determine the backup name of your images (&quot;path&quot;), the type of texture to be calculated, the resolution of the images, activate or deactivate functions such as the depth buffer (&quot;zbuffer&quot;), the blur, the background image, etc.


Once all these parameters have been set, all you have to do is click on the &quot;Render&quot; button.

For rendering go to Modules and then Render. Select the resolution, then under IMA select the name of the image. Move to FRA and indicate the level of fractal detail which of 4 is quite good. Then Keep to confirm and then reopen the window, pressing Render you will see the result. The image will be opened with any viewing program.


Strengths:

* Multi-window.
* Quality of rendering.
* Accuracy.
* Opening, preview and rendering on CyberGraphX screen.
* Extract / Convert Interp DEM, Import DLG, DXF, WDB and export LW map 3d formats 
* The &quot;zbuffer&quot; function.

Weaknesses:

* No OpenGL management 
* Calculation time.
* No network computing tool.


====Writing CD / DVD - Frying Pan====

Can be backup DVDs (4GB ISO size limit due to use of FileInfoBlock), create audio cds from mp3's, and put .iso files on discs

If using for the first time - click Drive button and Device set to ata.device and unit to 0 (zero)

Click Tracks Button - Drive 1 - Create New Disc or Import Existing Disc Image (iso bin/cue etc.) - Session File open cue file

If you're making a data cd, with files and drawers from your hard drive, you should be using the ISO Builder.. which is the MUI page on the left. (&quot;Data/Audio Tracks&quot; is on the right).

You should use the &quot;Data/Audio tracks&quot; page if you want to create music cds with AIFF/WAV/MP3 files, or if you download an .iso file, and you want to put it on a cd.

Click WRITE Button - set write speed - click on long Write button

Examples

Easiest way would be to burn a DATA CD, simply go to &quot;Tracks&quot; page &quot;ISO Builder&quot; and &quot;ADD&quot; everything you need to burn.

On the &quot;Write&quot; page i have &quot;Masterize Disc (DAO)&quot;, &quot;Close Disc&quot; and &quot;Eject after Write&quot; set.

One must not &quot;Blank disc before write&quot; if one uses a CDR


AUDIO CD from MP3's are as easy but tricky to deal with. FP only understands one MP3 format, Layer II, everything else will just create empty tracks

Burning bootable CD's works only with .iso files. Go to &quot;Tracks&quot; page and &quot;Data/Audio Tracks&quot; and add the .iso


====odf====

Every ODF file is a collection of several subdocuments within a package (ZIP file), each of which stores part of the complete document.

* content.xml – Document content and automatic styles used in the content.
* styles.xml – Styles used in the document content and automatic styles used in the styles themselves.
* meta.xml – Document meta information, such as the author or the time of the last save action.
* settings.xml – Application-specific settings, such as the window size or printer information.


To read document follow these steps:

* Extracting .ods file.
* Getting content.xml file (which contains sheets data).
* Creating XmlDocument object from content.xml file.
* Creating DataSet (that represent Spreadsheet file).
* With XmlDocument select “table:table” elements, and then create adequate DataTables.
* Parse child’s of “table:table” element and fill DataTables with those data.
* At the end, return DataSet and show it in application’s interface.


To write document follow these steps:

* Extracting template.ods file (.ods file that we use as template).
* Getting content.xml file.
* Creating XmlDocument object from content.xml file.
* Erasing all “table:table” elements from the content.xml file.
* Reading data from our DataSet and composing adequate “table:table” elements.
* Adding “table:table” elements to content.xml file.
* Zipping that file as new .ods file.

XLS file format

The XLS file format contains streams, substreams, and records.

These sheet substreams include worksheets, macro sheets, chart sheets, dialog sheets, and VBA module sheets. 
All the records in an XLS document start with a 2-byte unsigned integer to specify Record Type (rt), and another for Count of Bytes (cb). A record cannot exceed 8224 bytes. If larger than the rest is stored in one or more continue records.

* Workbook stream 
**Globals substream
***BoundSheet8 record - info for Worksheet substream i.e. name, location, type, and visibility. (4bytes the lbPlyPos FilePointer, specifies the position in the Workbook stream where the sheet substream starts) 
**Worksheet substream (sheet) - Cell Table - Row record - Cells (2byte=row 2byte=column 2byte=XF format)
***Blank cell record
***RK cell record 32-bit number. 
***BoolErr cell record (2-byte Bes structure that may be either a Boolean value or an error code)
***Number cell record (64-bit floating-point number)
***LabelSst cell record (4-byte integer that specifies a string in the Shared Strings Table (SST). Specifically, the integer corresponds to the array index in the RGB field of the SST)
***Formula cell record (FormulaValue structure in the 8 bytes that follow the cell structure. The next 6 bytes can be ignored, and the rest of the record is a CellParsedFormula structure that contains the formula itself)
***MulBlank record (first 2 bytes give the row, and the next 2 bytes give the column that the series of blanks starts at. Next, a variable length array of cell structures follows to store formatting information, and the last 2 bytes show what column the series of blanks ends on)
***MulRK record 
***Shared String Table (SST) contains all of the string values in the workbook.

ACCRINT(), ACCRINTM(), AMORDEGRC(), AMORLINC(), 
COUPDAYBS(), COUPDAYS(), COUPDAYSNC(), COUPNCD(), COUPNUM(), COUPPCD(), 
CUMIPMT(), CUMPRINC(), 
DB(), DDB(), DISC(), 
DOLLARDE(), DOLLARFR(), 
DURATION(), EFFECT(), FV(), FVSCHEDULE(), 
INTRATE(), IPMT(), IRR(), ISPMT(), MDURATION(), MIRR(), NOMINAL(), NPER(), NPV(), 
ODDFPRICE(), ODDFYIELD(), ODDLPRICE(), ODDLYIELD(), 
PMT(), PPMT(), PRICE(), PRICEDISC(), PRICEMAT(), PV(), RATE(), 
RECEIVED(), SLN(), SYD(), TBILLEQ(), TBILLPRICE(), TBILLYIELD(), 
VDB(), XIRR(), XNPV(), YIELD(), YIELDDISC(), YIELDMAT(),


&lt;pre&gt;
&lt;/pre&gt;


&lt;pre&gt;
&lt;/pre&gt;

&lt;pre&gt;
&lt;/pre&gt;

{{BookCat}}</text>
      <sha1>qryiirvipzevgciefebx3eplf24bssx</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/Platforms/Arm Raspberry Pi support</title>
    <ns>0</ns>
    <id>286123</id>
    <revision>
      <id>4669859</id>
      <parentid>4669685</parentid>
      <timestamp>2026-09-13T08:46:10Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669859</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94632" sha1="3p1urxs3lg7jfuo4viwu939qz0y0ym3" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*camdusbmidi detects midi devices with a preferences file (ENV:sys/midi.prefs) shows what hardware drivers loaded and ports activated 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>3p1urxs3lg7jfuo4viwu939qz0y0ym3</sha1>
    </revision>
    <revision>
      <id>4669861</id>
      <parentid>4669859</parentid>
      <timestamp>2026-09-13T09:10:55Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669861</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94692" sha1="3c4altvfck9fc13pifj0fepqdym285s" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) shows what hardware drivers loaded and ports activated 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>3c4altvfck9fc13pifj0fepqdym285s</sha1>
    </revision>
    <revision>
      <id>4669863</id>
      <parentid>4669861</parentid>
      <timestamp>2026-09-13T09:13:24Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669863</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94791" sha1="blw7aozg07szocmjudxeeoftnc1wkdq" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) shows what hardware drivers loaded and ports activated as there is no [https://www.youtube.com/watch?v=V93VPw2LNlA MIDI Ports preferences editor 2:30 in] 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>blw7aozg07szocmjudxeeoftnc1wkdq</sha1>
    </revision>
    <revision>
      <id>4669864</id>
      <parentid>4669863</parentid>
      <timestamp>2026-09-13T09:21:37Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669864</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94653" sha1="bgi9sln1a5jq5iaxqe5056uvmlwn531" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as auto setup?? 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>bgi9sln1a5jq5iaxqe5056uvmlwn531</sha1>
    </revision>
    <revision>
      <id>4669870</id>
      <parentid>4669864</parentid>
      <timestamp>2026-09-13T09:30:57Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669870</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94701" sha1="8mc5ao0s0trk3z515r2ylb2socf0ya5" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>8mc5ao0s0trk3z515r2ylb2socf0ya5</sha1>
    </revision>
    <revision>
      <id>4669873</id>
      <parentid>4669870</parentid>
      <timestamp>2026-09-13T09:47:59Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669873</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94766" sha1="p55116ea004hy6hz4bcdf6v20ihd1l0" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] possibly with [https://github.com/dwhinham/mt32-pi mt32-pi pi3+] 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


Need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [https://github.com/cnvogelg/amiditools amiditools]

[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>p55116ea004hy6hz4bcdf6v20ihd1l0</sha1>
    </revision>
    <revision>
      <id>4669876</id>
      <parentid>4669873</parentid>
      <timestamp>2026-09-13T10:05:34Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669876</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94847" sha1="7iru515id923ke2ifur6kxv536fb6br" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] possibly with [https://github.com/dwhinham/mt32-pi mt32-pi pi3+] as well as need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/CAMD_Toolkit CAMD_Toolkit], [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/cnvogelg/amiditools amiditools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [], 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>7iru515id923ke2ifur6kxv536fb6br</sha1>
    </revision>
    <revision>
      <id>4669877</id>
      <parentid>4669876</parentid>
      <timestamp>2026-09-13T10:15:42Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669877</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94948" sha1="2cqo9mzdkgyp5e8zx11ry1dqmx3juam" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] possibly with [https://archives.arosworld.org/?function=showfile&amp;file=driver/audio/usbmidi.i386-aros.lha usbmidi], [https://github.com/dwhinham/mt32-pi mt32-pi pi3+] as well as need developer to look at 64bit ports of [https://aminet.net/package/mus/midi/CAMD_Toolkit CAMD_Toolkit], [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/cnvogelg/amiditools amiditools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [], 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>2cqo9mzdkgyp5e8zx11ry1dqmx3juam</sha1>
    </revision>
    <revision>
      <id>4669878</id>
      <parentid>4669877</parentid>
      <timestamp>2026-09-13T10:16:45Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669878</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94948" sha1="obkb78yvmr1udxxv9iov3mg0yck1g0t" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] possibly with [https://github.com/dwhinham/mt32-pi mt32-pi pi3+] as well as need developer to look at 64bit ports of [https://archives.arosworld.org/?function=showfile&amp;file=driver/audio/usbmidi.i386-aros.lha usbmidi], [https://aminet.net/package/mus/midi/CAMD_Toolkit CAMD_Toolkit], [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/cnvogelg/amiditools amiditools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [], 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>obkb78yvmr1udxxv9iov3mg0yck1g0t</sha1>
    </revision>
    <revision>
      <id>4669879</id>
      <parentid>4669878</parentid>
      <timestamp>2026-09-13T10:18:14Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669879</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="94958" sha1="rgibi6hd8lrupm02vekgzp20q494uxs" xml:space="preserve">{{ArosNav}}

[[#Native]]

[[#Hosted]]

[[#Build]]

[[#Hardware]]

[[#References]]

[[#Future]]


==Introduction==


[[File:Scalos00.png|thumb|Scalos on Aros Pi3b]]

Aros aims to cover Pi 3 to 5 1Gb+ RAM ideally as you may have to switch to 256Mb gfx mode depending on the application running - it is still a work in progress 


Options to boot from using a good power source to prevent the yellow lightning symbol. 
Testing procedure is put sd card in, connect board to board if necessary, plug in hdmi and then power 
nothing else is done especially CSI DSI etc 
*With Pi3b+ the max you can get is 5.1V 2.5A with micro usb.
*With Pi4 5.1V 3A with usb-c 
*With Pi5 5.1V 5A, the amps went ever upwards, even to 5.1V 9A with usb-c 


Pi500+ keyboard wedge - 

Pi400 RPI-400 keyboard wedge - resolution changing and audio from micro hdmi0 (near 40pin) and micro hdmi1 (near usb-c psu) - Fn F10 0x5e power on and off works or held down for over 7 seconds auto shutdown - keyboard ok but not great - wifi and lan ethernet testing - 


* Pi 5 - Quad A76 64bit ARMv8 and RP1 &quot;southbridge&quot; with VideoCore 7 Pre-D0 (Rev1.0) or D0 (rev1.1) 
* Pi 4 - Quad A72 64bit ARMv8 with VideoCore 6 
* Pi 3 - Quad A53 [https://www.raspberrypi.com/documentation/computers/processors.html 64 bit] ARMv8 with VideoCore 4 with heatsink/fan on 3b to prevent cpu 82C+ throttling 


* Pi 2 - Quad 32bit ARMv6 with VideoCore 4 - mostly not 64bit compatible 
* Pi Model B+ 32bit ARMv6 with VideoCore 4 - not 64bit compatible 
* Pi Model A and B 32bit ARMv6 with VideoCore 4 - not 64bit compatible 


===Native===

* 2013-03 Kalamatee starts work
* 2015-04 Work continues with mschulz on the kernel and Kalamatee (NicJA) on gpio and usb
* 2018 [https://www.patreon.com/posts/i-owe-you-some-20956961 mschulz resume adding BE big endian support], [https://www.patreon.com/michal_schulz/posts Big endian on Pi]  
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bsek latest commits for pi 3b, 4 and 5 64bit] 
* 2026 [https://github.com/aros-development-team/AROS/commits?author=metaneutrons latest commits for Pi5]
* 2026 [https://github.com/aros-development-team/AROS/commits?author=bitplane latest commits for ARM]


'''Download''' [https://aros.sourceforge.io/nightly1.html RaspberryPi 3, 3+, 4 and 5 64bit ArmV8 builds] [https://sourceforge.net/projects/aros/files/ Alternative site and nightly2] both raspi-aarch64-system and raspi-aarch64-contrib can be unbz2'd and copied to fat32 8GB+ microSD card (there will be folders - boot c Classes Demos Developer Devs Extras etc only showing). The SD can be plugged in to the Pi 

64bit build works well on a single core LE little endian. Multicore [https://github.com/aros-development-team/AROS/commit/1df0747c2bda3523a43029725a709b1f377d84ec may follow]. Any issues booting could be down to the SD card so please use another SD to see if it is resolved. Please report your experiences in the [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80 Aros Raspberry pi 3 64bit thread] 

Boots with '''USB3''' port based sata3 ssd on Pi400 but untested on Pi4 (may need eeprom update from PiOS or Pi SD Imager) and Pi5 

Pi 3 B+ is pre-configured for USB sata3 boot - untested 

Pi 3 B may need [https://www.youtube.com/watch?v=ubnwvxF3Klc PiOS to set OTP to boot from usb - do so at your own risk] - if OTP set to usb, boot works but slower than SD card 

Speed write wise (top faster) 
&lt;pre&gt;
*NVME Pi5 untested    &gt;1000MB/sec  or faster if matched correctly 
*Sata3 ssd              500MB/sec
*SD        V90           90MB/sec  4K maybe 8K 
*SD        V60           60MB/sec  1080p 
*SD     U3 V30           30MB/sec  720p 
*SD C10 U1 V10 A1 A2     10MB/sec  minimum should be used now 
*SD C06                   6MB/sec  
*SD C04                   4MB/sec 
&lt;/pre&gt;


As a homage to the past, Aros shows a reduced number of icons but this can be changed by left mouse click in the window and then right click down to Window -&gt; View -&gt; All files


Like most amiga like OSs the audio and networking need to be setup manually 

Audio AHI prefs - Mode settings tab - needs both Music unit and Unit 0 set to RPiHDMI:16 bit stereo++  or RPiPWM:16 bit stereo++ at 44100Hz. Press '''Save or Use''' button after each choice 


Double left mouse click on most picture (Developer/Debug/Tests/Datatypes), audio and video files are supported, via datatypes, by the multiview application. 
Esc escape key usually closes open windows even the desktop 

Windows can be manipulated by the top (moving) and the bottom right corner (resizing) only. 

In Prefs/Appearance some decorative theming elements need work. There is a few Mason icons in /Prefs/Presets/Icons/Mason/ and the ever present default Gorilla - Icon exchange in works 


Printing only with Postscript but [https://github.com/bohunamiga/MintPRINT one] of [https://github.com/boingball/MintPRINT two] [https://github.com/Andiweli/AmiAirPrint/tree/main AirPrint] IPP has been attempted with [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2061&amp;pid=13954#post_13954 discussion] 


For more intensive graphics applications, you may need to edit config.txt in the root folder and change 128M to 256M to adjust more memory to graphics usage 


[http://archives.arosworld.org/index.php?function=browse&amp;cat=network/browser amelinium web browser] is available with an [https://eab.abime.net/showthread.php?t=122494&amp;page=51 eab thread] reminiscent of [https://github.com/zapek/Voyager Voyager] and to a lesser extent [https://github.com/amigazen/aweb3/ Aweb]. 

[[File:Wifi00.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi01.png|thumb|Setup wifi on Aros Pi3b]]
[[File:Wifi02.png|thumb|Setup wifi on Aros Pi3b]]

Wifi setup needs the network prefs with the TCP/IP tab click add interface -&gt; change Device to bwfm.device as net0:, IP Mode as DHCP and IPv4 

Once you’ve configured the device, simply save the Wireless Networks tab Wi-Fi configuration even if it’s empty. This will create the Wireless.prefs file in the Prefs/Env-Archive/SYS drawer, and should see the Wireless Manager icon in Wanderer. Although a reboot maybe necessary. Wireless tab gets your router settings. 

If it does not set to start at boot, settings are preserved. Instead, add this to the user-startup:
&lt;pre&gt;
execute sys:system/network/arostcp/s/startnet
run wirelessmanager device=bwfm.device &gt;nil:
&lt;/pre&gt;
Network will start automatically on boot. If you don't want the wirelessmanager icon on Wanderer desktop, just add 'nogui' to the wirelessmanager line


Lan ethernet port on 
*lan9514  Pi3b Pi2 no support at the moment 
*lan7515  Pi3b+ type into Device  usblan78xx.device as net0:  remove other device(s) 
*bcmgenet Pi4 Pi400 choose for Device bcmgenet.device  


Summary
*3b  ethernet not supported, setup wireless manager (with interface issues) 
*3b+ seems to work wifi and ethernet 
*4   untested 
*400 seems to work wifi and ethernet (with interface issues) 


There is normally no Bluetooth support for most amiga like OSs but Aros has one [https://github.com/aros-development-team/AROS/commit/6942cbfbf66426d21963a7fcd8aba6aff611a9e0 work in progress] [https://forums.raspberrypi.com/viewtopic.php?t=338466 firmware] 

*Bluetooth 4.1 BCM43430A1.hcd Pi3B, Pi3A, Zero W 
*Bluetooth 4.2 BCM4345C0.hcd  Pi3B+, Pi4 
*Bluetooth 5.0 BCM4345C5.hcd  Pi4B rev, CM4 and maybe Pi5 and CM5 

*bthid    keyboard mouse support 
*btserial serial 
*btpan    short range wireless connecting devices 


Only the Pi5 has a RTC real time clock, the other Pis will need to use Extras:Networking/utils/ntpsync/ or [https://archives.arosworld.org/index.php?function=browse&amp;cat=network PiNTP] to get the date and time from the internet 


USB classes support from Prefs/Trident is still work in process 
*usbaudio working on usb3 port (blue) on pi4, 400 but not working (no rt isochronous) on usb2otg (white or black) for pi3b, zero 2w 
*[https://aminet.net/package/mus/midi/camd camdusbmidi] detects midi devices without a preferences file (Prefs/Env-Archive/sys/midi.prefs) as [https://www.youtube.com/watch?v=RBxHkwy4Nrw auto setup now] possibly with [https://github.com/dwhinham/mt32-pi mt32-pi pi3+] as well as need developer gcc tools to look at 64bit ports of [https://archives.arosworld.org/?function=showfile&amp;file=driver/audio/usbmidi.i386-aros.lha usbmidi], [https://aminet.net/package/mus/midi/CAMD_Toolkit CAMD_Toolkit], [https://aminet.net/package/mus/midi/camdtools camdtools], [https://github.com/cnvogelg/amiditools amiditools], [https://github.com/timoinutilis/midi-sequencer-amigaos horny src], [https://aminet.net/package/mus/midi/horny-base horny-base], [http://bnp.hansfaust.de/index.html BnP], [], 


Regarding 680x0 emulation, there are several options that could be considered 
*[https://github.com/aros-development-team/AROS/blob/6722a0ae9e03fe5d26e32703360bd2059e0864cc/rom/m68kemu/README.md?plain=1#L424 m68kemu.library] for some Amiga productivity where the cpu is emulated and the system calls are redirected to Aros ones
*[https://github.com/BlitterStudio/amiberry amiberry] (winuae) for everything else like games 
*[https://github.com/jonx/AROS/tree/aarch64-darwin-graft/arch/all-darwin/libs/emu68k emu68k] 
*[https://scriptedamigaemulator.net/ Scripted Amiga] with [https://github.com/naTmeg/ScriptedAmigaEmulator ScriptedAmigaEmulator] or older [https://github.com/gbraad-amiga/ScriptedAmigaEmulator2 ScriptedAmigaEmulator2] 


[https://pinout.xyz/ GPIO 40 pins] [https://learn.sparkfun.com/tutorials/raspberry-gpio/gpio-pinout pinout] 

Some exceptions:

*Physical pins 27, 28 (GPIO0, 1) are an internal I2C bus and should not be used
*The other I2C on pins 3, 5 (GPIO 2, 3) can be used generally, but be aware they have permanent pull-up resistors to 3.3V
*For MIDI use USB but there are dedicated UART pins 8, 10 (GPIO 14, 15).

With a HAT it's more awkward -- you need to know which pins are used by the HAT and avoid them. Hopefully this will be documented.

Remember all GPIOs are 3.3V (not 5V tolerant), floating/noisy inputs can cause odd behavior, and that shorting the power supplies can cause instant death of the Pi.

In the shell 

 GPIO PIN/A/N,SET/N,GET/S,MODE/K,PULL/K

Controls and queries hardware GPIO pins via gpio.resource which is stored in the rom or Devs/ '''please test''' 

*PIN   -- (Required) Target GPIO pin number (e.g. 12).
*SET   -- Set pin output value to 0 (LOW) or 1 (HIGH).
*GET   -- Read and print current digital input level (0 or 1).
*MODE  -- Configure pin mode: IN (Input), OUT (Output), ALT (Alternate).
*PULL  -- Configure pull resistor: NONE, UP, DOWN.

EXAMPLES
&lt;pre&gt;
GPIO 12 MODE OUT
GPIO 12 SET 1
GPIO 12 GET
GPIO 13 PULL UP
&lt;/pre&gt;


[https://gpiozero.readthedocs.io/en/stable/installing.html Current] [https://gpiozero.readthedocs.io/en/v1.2.0/api_boards.html old support for gpiozero is unknown at present] [https://energenie4u.co.uk/res/pdfs/ENER314%20UM.pdf and associated 433MHz equipment] [ USA X10 security and lights via USB] [ OpenHab with Shelly Smart Plug connected over Wi-Fi, controlled by MQTT or HTTP] 


Youtube 

[], [], [https://www.youtube.com/watch?v=X4fmWAIv7FE Aros native on Pi3b], 

[], [], [https://www.youtube.com/watch?v=TSxlYb1eQWU Installed on Pi3b+], 

[], [], [https://www.youtube.com/watch?v=NFF1H3jCoz8 testing Aros native on Pi400], 

[], [], [https://www.youtube.com/watch?v=nIVx7mh1E1Q&amp;pp=ygUHYXJvcyBwadIHCQkTDAGHKiGM7w%3D%3D Aros on Thumb 2 based 32bit-ish ARM STM32H743 board], 


The status of AROS native ARMv6 for 32bit RasPi was OK. System booting, USB working (although with some issues but plans to fix them). 32bit native [http://www.aros.org/nightly1.html ARMv6 32bit nightlys] raspi-armhf-system raspi-armhf-contrib unbz2'd to fat32 microSD 


===Hosted===


AArch64 CPU backend for AROS, a Cocoa/Metal display, clipboard / host-volume / CoreAudio / BSD-sockets bridges, GPU 2D via gpufx.library, a 68k→AArch64 JIT (run68k), and a full Rust std port. On [https://www.jkn.me/blog/macaros-aros-on-apple-silicon/ latest Apple Silicon] [https://github.com/jonx/Macaros early buggy alpha version of hosted Aros .dmg on MacOS12+]. Please use [https://github.com/jonx/Macaros/issues MACAros github] for issues, features etc and possibly [https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2030&amp;pid=13910#post_13910 here] 


[http://www.aros.org/snapshots1.html old linux and android hosted 32bit] 


===Good sites to visit===

*[https://github.com/raspberrypi/firmware/tree/master/ Raspberry Pi Firmware build] 
*[https://www.raspberrypi.com/documentation/computers/software-sources.html Documentation] 
*[https://rpilocator.com/ RPiLocator] 


Linux only
*[https://github.com/raspberrypi/linux Raspberry Pi Linux Build] 
*[https://www.raspberrypi.com/software/operating-systems/ PiOS Lite] and then [https://hstwb.firstrealize.com/ HST] 
*[https://dietpi.com/ DietPi] 
*[http://www.tinycorelinux.net/ports.html piCore]
*[https://wiki.alpinelinux.org/wiki/Raspberry_Pi Alpine Linux] 
*[https://github.com/armbian/build Armbian] 
*[ PiMiga] 

*[ FydeOS]
*[ TwisterOS based on ChromiumOS] 
*[https://note.com/jamesmondo/n/nc76e31402be8?hl=en BSD] 


Other alternative lighter smaller than Pi OS 
*[https://aros.sourceforge.io/nightly1.html Aros 64bit ARMV8 single core] 
*[https://www.riscosopen.org/wiki/documentation/show/Welcome%20to%20RISC%20OS%20Pi RiscOS on Pi3 and Pi4]
*[https://github.com/michalsc/Emu68 ARM based realtime JIT 68k for amiga computers] 
*[https://github.com/JJDSNT/bellatrix/releases/ Alternative use of Emu68 on Pi3b] 
*[https://github.com/stevereaver/uaos uaOS with Emu68k] 
*[https://github.com/aros-development-team/AROS/commit/f80a268607dfae81b2db94755ab4e4d31ccb72d6 m68kemu library reference] 
*[ HaikuOS]
*[https://github.com/raspberrypi/noobs NOOBS] os loader with successor [https://github.com/procount/pinn PINN] 
*[https://github.com/maxnet/berryboot berryboot]

*[https://github.com/brianwiddas/pi-baremetal Bare Metal Access on Pi 32bit] 


==== Hosted ====

=====64bit=====

[https://www.arosworld.org/infusions/forum/viewthread.php?thread_id=2019&amp;rowstart=80&amp;pid=13667#post_13667 Linux hosted Pi build] 

[https://github.com/BlitterStudio/aros-compiler-docker Aros Docker for various systems], 

[https://github.com/aros-development-team/AROS/commit/d84b9a337f9aa059154d9af69275935125166bdd Apple Silicon support]


=====32bit=====

Ubuntu VM approach to compiling [http://lallafa.de/blog/2013/06/building-aros-hosted-for-raspbian/ Linux hosted AROS June 04, 2013]

 ../AROS/configure --target=linux-armhf  --enable-includes=/usr/arm-linux-gnueabihf/include --x-includes=/usr/arm-linux-gnueabihf/include --x-libraries=/usr/arm-linux-gnueabihf/lib

arm-elf- is symbol-linked to arm-linux-gnueabi- (arm-linux-gnueabi- is more correct in this case, because it's going to be compiling the ARM AROSBootstrap for ARM Linux)

*armel - many of the &quot;android&quot; machines require since the entire OS is made for soft float VFP. 
*armfp - Efika MX target, Raspberry PI, EfikaMX, Pandora and virtually everything (VFP)

Keep in mind it's possible to start hardfp AROS hosted on softfp system, though, as long as no calls between AROS and host require floating point parameters. NOTE: hardfloat objects *cannot* be linked with softfloat objects - they have a different ABI.

Just keep in mind the arm nightly build machine is quite complex beast. It needs the x86_64 host compiler to compile AROS tools. The arm version is built every night using gcc-4.6.2 crosscompiler (built together with AROS) and successfully builds armel and armhf linux hosted targets.

*needs an AROS code compiler for ARM target 
*as well as unix compiler for ARM linux host (would be best to have both softfp and armhf, we have softfp only now) with full set of libraries and includes.

with—disable-crosstools  $AROS_CC  is always a wrapper around $KERNEL_CC  ?  If  so,  this  is  wrong for some ports. This can break Darwin, Windows and Android port. 
Yes,  Android  port  will  build.  And  even  work. But it's not good because  the  port  will  not  be ABI-compatible with other ARM ports. Android's ABI is different from GNUEABI. For example:

&lt;pre&gt;
enum test {foo, bar};
enum test testvar;
&lt;/pre&gt;

sizeof(testvar)  will  be  equal  to sizeof(int) in GNUEABI (Linux and AROS)  and  sizeof(short)  on  Android. This affects linking objects from static linklibs, for example.

Previously everything worked because $AROS_CC was a wrapper on top of $HOST_CC. And a real crosscompiler was used on non-ELF hosts.

Android is the same. $KERNEL_CC is incompatible with AROS.

compiler=kernel  is  appropriate _ONLY FOR CODE WHICH RUNS ON HOST OS_ (or  barebone  hardware,  if  we  talk  about  native).  This includes bootstraps,  their  linklibs, and host-side dynamic libraries (Windows makes extensive use of them because of architectural considerations.

No single AROS object should be compiled with this setting. $KERNEL_CC is really compatible with AROS *ONLY IN LINUX-HOSTED* and no more. On other systems (Darwin, Windows,  Android) this is not true any more, and compiler=kernel is never going to work.

If  you  want  to  compile your AROS module against host OS includes, append  the  following  to  USER_INCLUDES  (or  USER_CFLAGS,  this  is effectively the same):

 -isystem $(GENINCDIR) $(KERNEL_INCLUDES)

$(KERNEL_INCLUDES) expands to:

 -isystem  &lt;your_os_includes&gt;  -isystem  &lt;host_OS_gcc_private_includes&gt;
 -nostdinc

This makes AROS compiler adhering to host OS APIs.

If you want some preprocessor symbols based on what your host OS actually is, add something like -DHOST_OS_$(AROS_HOST_ARCH).

Why is there $(GENINCDIR) at all? Because host OS has its own libc includes, which would conflict with AROS ones. And the host OS libc is not binary-compatible with AROS one.

Why doesn't Windows-hosted port use $(KERNEL_INCLUDES) ? Because WinAPI includes conflict with AROS ones in fundamental typedefs, like WORD, BYTE and BOOL. It's almost impossible to deal with this in any other way than rewriting WinAPI definitions using AROS types.

Building under centos 6.3 (i386) currently, and AROS creates the toolchain itself. haven't yet committed the necessary changes but &quot;./configure --target=raspi-armhf&quot; is enough to start, then &quot;make arosboot-raspi&quot; will generate arosraspi.img (containing the bootstrap, kernel.resource, and exec.library) as well as arosraspi.rom (containing all the other essentials components such as dos, graphics etc).  It will also copy over a config.txt file to make the raspi bootstrap code load the correct kernel, and a cmdline.txt that enables exec debug output.

*armel = typically Debian 6, Ubuntu Maverick, Android, 
*armhf = typically Debian 7, Debian 8, Ubuntu Precise,

Cross-compiling Ubuntu ARM softfp 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armel' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armel] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armel.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabi libx11-dev:armel libsdl-dev:armel
&lt;/pre&gt;

&lt;pre&gt;
 ./configure --target=linux-arm --x-includes=/usr/include \
             --enable-includes=/usr/arm-linux-gnueabi/include
&lt;/pre&gt;

Cross-compiling Ubuntu ARM hard-float 
&lt;pre&gt;
    sudo sh
    echo 'foreign-architecture armhf' &gt;&gt;/etc/dpkg/dpkg.cfg.d/multiarch
    echo 'deb [arch=armhf] http://ports.ubuntu.com/ precise main universe' &gt;/etc/apt/sources.list.d/armhf.list
    apt-get update
    apt-get install gcc-arm-linux-gnueabihf libx11-dev:armhf libsdl-dev:armhf
&lt;/pre&gt;

&lt;pre&gt;
    ./configure --target=linux-armhf --x-includes=/usr/include \
                --enable-includes=/usr/arm-linux-gnueabihf/include
&lt;/pre&gt;

Now, the AROS build is configured properly and all you need to do is:

 make


==Build==

===64bit===


===32bit===


# download/checkout the source someplace, e.g. /build/AROS-Src/
# make a directory to store external sources AROS downloads, e.g. /build/Ports
# make a build directory, e.g. /build/aros-raspi-armhf
# cd into the build dir, configure, and then run make -:

&lt;pre&gt;
&gt;cd /build/aros-raspi-armhf
&gt;/build/AROS-Src/configure --target=raspberrypi-armhf --with-serial-debug --enable-ccache --with-portssources=/build/Ports
&gt;make
&gt;make arosboot-raspi
&lt;/pre&gt;

then copy the files from /build/aros-raspi-armhf/bin/raspi-armhf/AROS/ onto an sdcard, and download/copy the Raspi firmware files onto it.

You should then be able to boot the sdcard on your RasPi.

The current W.I.P tree to svn. it can be built as follows ..
&lt;pre&gt;
./configure --target=raspi-armhf
make arosboot-raspi
&lt;/pre&gt;

That will generate arosraspi.img, arosraspi.rom and config.txt in bin/raspi-arm/AROS - so either copy just those files to a fat formatted SD card (with the firmware files on), or copy the whole contents of the AROS folder.

NB - if you have a Linux/other install, backup the existing config.txt first

arosraspi.img contains the bootstrap (which has very basic mailbox code, framebuffer/gpio init, and console &quot;emulation&quot; via code pinched from our libbootconsole), kernel.resource, and exec.library

arosraspi.rom contains all the other components needed to boot AROS.

The config.txt file will tell the RasPI bootstrap to load the arosraspi kernel and ramdisk (rom).

the bootstrap has minimal mailbox code, planning on adding either a resource or library that driver/app code will use to access it (likewise for GPIO)


Help building AROS hosted on Linux ARM

Was looking a way to use more my Handheld ARM based called Pyra (Dragonbox Pyra) an ARM (Omap5 cpu with 4GB ram) linux based machine (Debian Buster v10 with kernel 5.6.19 adapted) and have a try to compile the latest Aros sources by Deadwood directly on this device.
Compilation stops after build libpopupmenu.a and trying to build libatomic have this error:

&lt;pre&gt;
    Configuring build in bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic
    configure: WARNING: unrecognized options: --disable-nls, --without-x
    checking for --enable-version-specific-runtime-libs... no
    checking for --enable-generated-files-in-srcdir... no
    checking build system type... arm-unknown-linux-gnu
    checking host system type... arm-unknown-aros
    checking target system type... arm-unknown-aros
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for arm-aros-strip... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-strip
    checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking for arm-aros-gcc... /media/farox/pyra2/arosbuilds/toolchain-core-armhf/arm-aros-gcc
    checking whether the C compiler works... no
    configure: error: in /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic':
    configure: error: C compiler cannot create executables
    See config.log' for more details
    make[2]: *** [mmakefile:4489: /media/farox/pyra2/arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic/.configured] Error 77
    [MMAKE] make --no-print-directory TOP=/media/farox/pyra2/arosbuilds/toolchain-core-armhf-build SRCDIR=/media/farox/pyra2/arosbuilds/AROS CURDIR=tools/crosstools/gnu TARGET=tools-crosstools-gcc-libatomic-configure -s --file=mmakefile tools-crosstools-gcc-libatomic-configure failed: 512
    [MMAKE] Error: Error while running make in tools/crosstools/gnu: No such file or directory
    make[1]: *** [Makefile:361: linklibs-libatomic] Error 10
    make: *** [Makefile:183: crosstools] Error 2
&lt;/pre&gt;


looking at config.log on arosbuilds/toolchain-core-armhf-build/bin/linux-arm/gen/host/tools/crosstools/gnu/gcc/arm-aros/libatomic

found that arosbuilds/toolchain-core-armhf/arm-aros-ld: cannot find -laeabi
so do make linklibs-aeabi-arm-quick
and the missing lib was built.

now the next stop is at
fatal error: bits/libc-header-start.h: No such file or directory
and
fatal error: sys/cdefs.h: No such file or directory
in many places so after checking that have this missing include files i have noted that my include path is a bit different, standard searching path is /usr/arm-linux-gnueabihf but in my system is /usr/include/arm-linux-gnueabihf
so if i add my path to some mmakefiles compilation goes on....but is a better way to add this path to avoid every mmakefiles to be changed?

fixed with adding
-I/usr/include/arm-linux-gnueabihf
to where is missing on mmakefiles like
USER_INCLUDES := -isystem $(GENINCDIR) -I/usr/include/arm-linux-gnueabihf $(KERNEL_INCLUDES)

P.s. I have changed many mmakefiles and have at least compiled (after many hours) the toolchain doing make every time in arosbuilds/toolchain-core-armhf-build (also have to disable making tests under cplusplus but don't remember the directory ...) but ask an help to have an automated way to correctly build without modify mmakefiles.


Last time built armhf target was around 2 years ago. At that point built is via cross-compilation from linux (ubuntu 22.04) using linux armhf crosscompiler (this can explain the path differences you are experiencing) as well as using AROS gcc cross-compiler in version 6.5.0 (build with option 21) in rebuild.sh). Since then AROS GCC has been updated to 10.5.0 and don't believe anyone tried to build the armhf target again.

My suggestion would be to downgrade GCC to 6.5.0 (via editing AROS/config/gcc_def file) and try to first build using cross-compilation from x86_64 linux. Once that works, you will have a &quot;template&quot; to compare to native compilation under arm linux.


Thanks for your suggestion...but think the toolchain with GCC 10.5.0 is compilable if i found a way to pass the path of my system to the script that build (option 21 on rebuild).
The other only changes are (but don't know where to modify...) is to add the build of libaeabi and disable the building of some tests under cplusplus that use exceptions and is not supported under ARM. try to crosscompile with my Linux amd64 PC.

For paths look into core-linux-armhf/bin/linux-armhf/gen/config/target.cfg. A number of build-wide variable is set there containing paths to local build system. These variables and the target.cfg file are generated by AROS ./configure script.

Thanks compilation now go forward...changed target.cfg under &quot;toolchain-core-armhf-build/bin/linux-arm/gen/config&quot; and do make on &quot;toolchain-core-armhf-build&quot; dir.

Need to find where to enable build libaeabi.a so can build the entire toolchain with option 21 of rebuild.sh


Found something that looks like libeabi in AROS/arm-all/arm-aeabi/mmakefile.src. Try adding a third line there:

#MM- linklibs-armhd : libklibs-aeabi-arm

Don't remember needing this library. Possibly the 6.5.0 GCC somehow does this while 10.5.0 is missing this.

Try adding this line (and the variant &quot;linklibs-armhf&quot; instead of hd) but it did not solve the automatic building of the missing lib. I must do &quot;linklibs-aeabi-arm-quick&quot;.
Anyway after have build the aeabi lib i succefully built the toolchain (after many hours...). Smile

To test I restarted from selecting option 21 (on rebuild.sh) but after many hours i get the same error of the kernel includes not found...maybe i need to modify the configure script for my case.

With the toolchain built i try to build the core-linux-armhf (DEBUG) (option 22) but after a while it stopped with
&quot;cannot find -laeabi &quot; so i made it built manually...and now i can continue compiling...i'll let you know if all goes ok.


== Hardware ==

===64bit===


====BCM2712====

With the Pi5 

Broadcom VideoCore 7 vc7 is an integrated GPU with 12 cores and up to 800 MHz clock. VideoCore VII is capable of OpenGL ES 3.1 and Vulkan 1.2. The driver support for the Raspberry Pi continues to build upon the [https://lore.kernel.org/dri-devel/20230928114532.167854-1-itoral@igalia.com/ open-source V3D driver] stack within [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25450 Mesa] hopefully be merged for Mesa 23.3 

*Raspberry Pi M.2 HAT+ Expansion Board 
*Geekworm X1001 PCIe to M.2 Key-M NVMe
*Geekworm X1003 PCIe to M.2 HAT NVMe SSD PIP Board for Raspberry Pi 5 
*Pineboards Pi Hut HatDrive! M.2 HAT 2024/V4 
*Hat+ Gen2 Gen3 Nvme
*GeeekPi 52Pi N04 for Raspberry Pi 5 NVME M.2
*


*2024 RPI AI HAT    - Hailo  20TOPs  no LLMs 
*2026 RPI AI HAT+ 2 - Hailo  40TOPs  slightly better? 


[https://www.raspberrypi.com/documentation/accessories/camera.html Cameras for Pi]
*Raspberry Pi camera module, the V3 with Sony IMX708 back-illuminated CMOS 12 Megapixel sensor
*Raspberry Pi Camera Module V2 – 8MP Sony IMX219 Sensor
*Raspberry Pi camera Rev 1.3, 5MP 1080P OV5647 image/video module, 2592 x 1944 pixels


====BCM2711====

With the Pi4 an ARM a72 cpu is about x3 times the size of an a53 in the Pi3 

the 2711b line used more power when idle, compared to the 2711c 

*2018 Raspberry Pi PoE HAT Power Over Ethernet Hat - design issues 
*2020 Raspberry Pi PoE+ HAT Power Over Ethernet Hat Pi3b+ Pi4 only - better design 
*Waveshare PoE HAT (B) with cooling fan for Raspberry Pi 3B+/4B 802.3af PoE 

*[https://github.com/axizo-pi/V3DLib vc6 V3D 4.2] is derived from [https://docs.broadcom.com/doc/12358545 vc4], but it is significantly different 
The QPU pipeline stays mostly the same, you still have an add ALU and a multiply ALU and it can issue two ALU OPs per cycle. There is still 4 SIMD lanes, interleaved over 4 cycles.
The instruction encoding for the QPUs is different, but the core instructions are the same.

Instructions for packed 8 bit int math has been dropped, along with most of the pack modes.
Instructions for packed 16bit float math has been added (2 floats at in a single operation)
With vc5/vc6, you write two packed 16f value to the tilebuffer (or four writes of 32f, if you are using the rgba32f framebuffer). And there is a handy vfpack operation which allows you to pack two f32s into a single 32bit value in a single instruction. You can vfpack directly into the tile buffer register.

the multiply ALU can now fadd, so you can issue two fadds per instruction. the add ALU has gained a bunch of new instructions 

the A and B register files have been merged. You still only get an A read and a B read per instruction, but they read from one big register file (which means the underlying memory block has gone from two sets of &quot;one read port, one write port&quot; to one &quot;two read ports, one write port&quot; block)

The theoretical max FLOPs per QPU remains the same at two per cycle, other than the bump from 400mhz to 500mhx but it looks like a lot of effort has been put putting those theoretical FLOPs to better use. 
*vc4 could run one or two threads per QPU. When you ran in two thread mode, the available register file halfed to 32 registers.
*vc5 added a four thread per QPU mode, with 16 registers per thread.
*vc6 doubled the size of the register file. You could now use all 64 threads in two thread mode and 32 registers in for thread mode. Single thread mode was removed, you always have at least two threads.

With the threading improvements, the QPUs should spent much less time idle waiting NOPs for memory requests. Most of the design changes have gone to improving the fixed function hardware around the QPUs. A fixed function blend unit has been added, which should reduce load on the QPUs when doing alpha blending. hope software blending is still possible 

The tile buffer can now store upto 4 render targets (up to 128bits per pixel, so if you are using 4 32bit render targets, you can't have a depth buffer)

A MMU, allowing a much simpler/faster kernel driver.

Many more texture formats, framebuffer formats.

All the features needed for opengl es 3.0 

H.265 / HEVC decoder is a HEVCv2 Main 4:4:4 10 design supporting bitstreams up to profile 5.1
HEVC hardware decode supports 4kp60, 10-bit. Audio output is pretty much unchanged, but the HDMI audio channels now support 8x192kHz bitrates 

Each ALU typically have 2 floating point operators, and as you pointed out in a earlier post videocore 6 is no exception, with both a multiply and additive floating point operator. Thus theoretical GFLOPs are calculated with both operators in mind. That is what the 2 in my formula represents, and is common across any modern programmable shader, whether you calculate Nvidia, AMD, Intel, Boardcom or any other company's GPUs. Total ALUs * 2 * GHz clock = GFLOPs, In the case of Raspberry Pi 3, it's 24 ALUs * 2 operators * 0.4GHz = 19.2GFLOPs
If the Videocore 6 does indeed only have 16 ALUs (16 * 2 * 0.5GHz), you'd have only 16GFLOPs but they are better utilised 

Possible maximum performance 
&lt;pre&gt;
VideoCore IV @ 250MHz: 250 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 24 Gflop/s
VideoCore IV @ 300MHz: 300 [MHz] x 3 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 28.8 Gflop/s
VideoCore VI @ 500MHz: 500 [MHz] x 2 [slice] x 4 [qpu/slice] x 4 [processor] x 2 [op/clock] = 32 Gflop/s
&lt;/pre&gt;

Faster LPDDR4 memory.


====BCM2837==== 

With the Pi3 
* Broadcom BCM43438 chip provides 2.4&amp;nbsp;GHz 802.11n wireless LAN, Bluetooth Low Energy, and Bluetooth 4.1 Classic radio support, 3B+ [https://github.com/aros-development-team/AROS/commit/afa5bc0bb17d5dd06bcfdbac00853a3799ca8d76 LAN7515] 

The overclock ability has diminished with each chip version as the energy usage has increased. BCM2837 is one of the warmest yet and benefits from active fan cooling if all four cpu cores are in use for a short while. Video playback is not affected due to the custom support in the GPU. 5 V / 2.4 or 2.5 amp power supply recommended if all four cpu cores are running, else throttling (cpu slowdown) might occur. 

Dual VDP and scalable QPU in VC4 


ARMv8-A has [https://developer.arm.com/documentation/102412/0100/Privilege-and-Exception-levels privilege levels] where userspace typically runs at ‘EL0’, the kernel at ‘EL1’ or ‘EL2’ and the firmware at the highest level ‘EL3’. 


===32bit===

=== Core Kernel ===


====BCM2708(family)====
which includes the [http://elinux.org/RPi_Hardware BCM2835] (ARM1176JZF-S 700&amp;nbsp;MHz CPU + VideoCore IV GPU + up to 1GB RAM)

*Framebuffer (fb) using mailbox 
*IRQ scheduler, etc 
*Arasan based SD Card controller 
*Synopsis DesignWare USB 2.0 OTG controller [http://networkdirection.net/index.php?option=com_content&amp;view=article&amp;id=106:rasperry-pi-usb-controller&amp;catid=45:raspberry-pi&amp;Itemid=54 Unofficial DOCS pdf],  [dwc_otg.c FreeBSD], [], [https://www.riscosopen.org/viewer/view/mixed/RiscOS/Sources/HWSupport/USB/Controllers/DWCDriver/ RiscOS USB Driver], [https://www.riscosopen.org/forum/forums/5/topics/878 RiscOS USB Discussion], [https://www.riscosopen.org/forum/forums/11/topics/1893 Other USB RiscOS], [http://plan9.bell-labs.com/plan9/index.html Plan9 Miller's usb] http://plan9.bell-labs.com/sources/contrib/miller/, [https://github.com/Chadderz121/csud CSUD driver], 
*[http://www.smsc.com/media/Downloads_Public/Data_Sheets/9512.pdf SMSC 9512] USB LAN/Hub chip 
*CMOS RAM 
*VCHIQ port which sends messages to the GPU e.g. for mouse, keyboard, audio on HDMI, etc 
*Audio Driver 
*Serial Peripheral Interface Bus (SPI) 
*[http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/ I2C registers]
*I2S 
*Universal Asynchronous Receiver Transmitter (UART) 
*[http://elinux.org/RPi_BCM2835_GPIOs GPIOs] and [http://www.adafruit.com/blog/2012/08/17/broadcom-bcm2835-peripheral-memory-map-and-gpio-alternate-use-chart-piday-raspberrypi-raspberry_pi/ Alternative view of GPIO]

BCM2836 
* For Pi B+, PI 2 and Pi 3 SMSC LAN9514 chip adding 10/100 Ethernet connectivity and four USB channels to the board

*[http://www.andrewscheller.co.uk/rpi_pcb_modules.html PCB], [http://elinux.org/RPi_Low-level_peripherals Low level features],


 Implemented so far... 

# Modify the configure system so that it correctly builds for the arm hardware float raspi target.
# Implemented the bootstrap to load the aros modules and prepare the arm to jump into them. Reworked the x86 console support so that parts can be stolen for raspi to use since t has no basic functionality to output to the display.
# Implemented a kernel.resource to prepare the raspi for running aros and provide the low level api calls to expose available resources and allow exec, etc function.
# Implemented serial debug support
# Implemented the exec (and kernel) functionality required to make multitasking work (and interrupts, exceptions, syscalls, etc)
# Implemented a timer.device to utilise the hardware timers.
# Implemented a very basic gfx driver to expose the hardware's framebuffer.
# Implemented an SD-Card driver for AROS which presently only supports the raspi's chipset but can easily be modified to support all sd-card hardware and media.
# Fixed the fat filesystem support in AROS so that it can boot on RasPi's normal SD-Card setup. The &quot;rom&quot; image files needed use a different filename than the default linux, etc images so can be easily installed without harming the existing files - you only need to change the loaded images in the config file to get aros to boot.
# Updated the build scripts to automatically download the necessary raspi firmware files and wrap it all up so that you can simply extract the archive to a fat formatted sdcard and boot it on the raspi without having to get anything else.
# fix everything in contrib and ports to build for raspi (needs proper testing/fixes but allows every component to actually compile at least, including owb) + numerous other fixes to get things working on arm/raspi ..


Improvements...

# Implement a USB chipset driver &quot;OR&quot; finish the existing one [https://github.com/aros-development-team/AROS/commit/c07d13c724f944674be5db54fc6a71ee72a01809 usb otg] - the current code is mostly a skeleton that should initialise the chipset and then needs relevant code to support the different transfer types. It also has the &quot;virtual&quot; hub code in place to represent the raspi's USB port (from poseidons p.o.v) 
# Implement a driver for the USB NIC (a few weeks - depends on USB above) 
# Write an [https://github.com/aros-development-team/AROS/commit/d55d0f74d20b769bbb8c8d386e5c1d7a9154f05a audio driver] (a few weeks - independent of USB) and [https://github.com/aros-development-team/AROS/commit/e93a4c245f27a87c9c4c1d39206694b39059998a HDMI]
# fix syscall bug in the current raspi kernel code
# Graphics depend on having a decent &quot;bcmdma.resource&quot; implemented as to use the cpu's dma engine. The sd card driver needs to use it for transfers to/from the controller - and the gfx system needs to use it for &quot;blitting&quot;. 
# [https://github.com/aros-development-team/AROS/commit/4019d84e4975d4dad987a12d57fe108f5ac048e6 Improve the gfx driver], [ vc4gfx HIDD] add [http://dri.freedesktop.org/wiki/VC4/ Gallium3D support] 
# [https://github.com/aros-development-team/AROS/commit/b13905b3e8e45b089f520b44692c81affddd066f Improve] the [https://github.com/aros-development-team/AROS/commit/3a876755c070f5c73c4f53c7f4d35b4f923088b9 sdcard] device driver  - which is also pretty basic but should work with most cards, rework it to also support pci, etc. sd card interfaces on x86 
# The current code using very rudimentary access to the gpio interface - so that should be implemented as some resource for other components to access, as-well as the i2c interface exposed over the gpio interface. that should have a hidd class implemented which uses the gpio resource to communicate.


 Boot up typical for most other OSs before the open sourcing of many binary blobs from 2017 onwards 

On power-up, the rpi [http://www.open.com.au/mikem/bcm2835/ BCM 2835] [https://github.com/hermanhermitage/videocoreiv VideoCore4] GPU, not the ARM CPU, is in control, and the SD card slot is the only peripheral device with power. The firmware burned into the BCM2835's VideoCoreIV GPU PROM requires a DOS-style partition table; a FAT-formatted first partition; and the freely redistributable but closed sourced Broadcom files “bootcode.bin” and “start.elf” in that partition.

The boot sequence carries out several pre-boot tasks

*On powering of the rpi, the GPU reads and executes bootcode.bin, which then loads start.elf 
*The GPU loads the “start.elf” file, eventually, into the L2 cache and then executes it
*configures the memory split for the CPU and GPU
*reads and parses “config.txt” from the same partition on the SD card and applies the settings (like a PC’s BIOS settings)
*loads the “kernel.img” file, again from the same partition
*activates the CPU to begin executing the loaded kernel image

The CPU/GPU memory split is hard-coded into start.elf, so Broadcom provides three start.elf images, to give 32M, 64M, or 128M to the GPU for multimedia performance, and the remainder to the CPU.

RPi uses [https://github.com/raspberrypi/firmware some closed source loaders] and at some point it loads a binary blob named &quot;kernel.img&quot; at 0x8000, at that point there would be a rudimentary Aros alive. If one wants to use the SD-card then there would have to be a driver for the interface and a fat filesystem handler (SD-card has to be formatted to fat filesystem)

Boot code and kernel are now linked together and made into that binary blob, just for starters. Raspberry Pi uses [http://kernelnomicon.org/?p=133 u-boot] and [http://kernelnomicon.org/?p=138 UBoot] as bootloader, there's already some code in the Efika MX port for that. UBoot is a native bootloader and not just for the raspberry pi, it loads after start.elf.

You can find Efika MX port from arch implementations, some hacking is needed for the mmakefile.src'es as iit dates back to before the Aros crosstool era or else you get some weird errors while building. You also need to code the bootstrap and serial handling.

At the moment it seems that a fastest route for the native build would be to make one binary blob without using the package system. Raspberry's memory layout is pretty simple and if the implemented u-boot doesn't support loading other modules 

&lt;pre&gt;
?          - alias for 'help'
mtest      - simple RAM test
autoscr    - run script from memory
base       - print or set address offset
bbm        - BBM sub-system
bdinfo     - print Board Info structure
boot       - boot default, i.e., run 'bootcmd'
bootd      - boot default, i.e., run 'bootcmd'
bootm      - boot application image from memory
bootp      - boot image via network using BootP/TFTP protocol
cmp        - memory compare
coninfo    - print console devices and information
cp         - memory copy
crc32      - checksum calculation
echo       - echo args to console
fatinfo    - print information about filesystem
fatload    - load binary file from a dos filesystem
fatls      - list files in a directory (default /)
go         - start application at address 'addr'
help       - print online help
iminfo     - print header information for application image
itest      - return true/false on integer compare
jade       -
loadb      - load binary file over serial line (kermit mode)
loads      - load S-Record file over serial line
loady      - load binary file over serial line (ymodem mode)
loop       - infinite loop on address range
md         - memory display
mm         - memory modify (auto-incrementing)
mtest      - simple RAM test
mw         - memory write (fill)
nfs        - boot image via network using NFS protocol
nm         - memory modify (constant address)
pci        - list and access PCI Configuration Space
ping       - send ICMP ECHO_REQUEST to network host
printenv   - print environment variables
rarpboot   - boot image via network using RARP/TFTP protocol
reset      - Perform RESET of the CPU
run        - run commands in an environment variable
saveenv    - save environment variables to persistent storage
saves      - save S-Record file over serial line
setenv     - set environment variables
sleep      - delay execution for some time
tftpboot   - boot image via network using TFTP protocol
USB        - USB sub-system
usbboot    - boot from USB device
version    - print monitor version
&lt;/pre&gt;


And there is one more thing about modular ports. In order to actually implement this, your bootstrapping environment should provide the ability to load several files. On PC this is provided by GRUB2. on CHRP you can read filesystem via OpenFirmware, and Sam's Parthenope relies on modified u-boot. If your bootstrap allows to load only a single file, then you stuck with monolithic kickstart. By the way...  u-boot allows not only to boot up a single uImage or zImage, it also allows to write client programs AFAIK. With this approach, you actually can write modular bootstrap for ARM AROS using unmodified u-boot.

Most used [http://www.compulab.co.il/workspace/mediawiki/index.php5/U-Boot_quick_reference uboot options] are fatls usb 0:1,

the reason behind INTB_KERNEL is to allow use of the standard Exec function AddIntServer() to add interrupt handlers for
hardware drivers etc. AmigaOS never used it for abstract hardware drivers. AmigaOS  routed  only  raw  hardware IRQs there. Their assignment was hardcoded. As well as number of them. Actually on AmigaOS every bus has its own interrupt subsystem. For example PCI bus. PCI interrupts on Amiga are routed to a single exec interrupt.  1:1 relationship between CPU  and hardware interrupts is present only on PC.

IMHO we miss things like AddInterrupt/RemInterrupt methods on our PCI subsystem's device class.  PCI bus class should map these methods to whatever is appropriate. This is how it is done on AmigaOS and friends. When these are implemented, raw kernel.resource API will be needed only for several PC-specific drivers with hardwired resources. Exec IRQs are real IRQs only on Amiga hardware. On other machines they can be emulated where appropriate (VBlank is a good example). kernel.resource is meant  to be different, its IRQs are hardware-agnostic, they are plain &quot;Hardware IRQ number X, whatever this means&quot;. They are low-level actually, and meaningful only in the context of a particular system.

Was that not the transition from irq.hidd to kernel.resource? No.  A long time ago there was another hacky bit named INTB_TIMERTICK. It was &quot;abstract timer interrupt&quot;, used by timer.device. It was the same as VBlank, but with larger frequency. I removed it, because kernel.resource API was a cleaner way to access this interrupt. Furthermore, there can be more than one timer in the system. Thinking about bringing back timer HIDD definitions again. hpet.resource is a bad idea.

Can someone please enlighten me a little on how the scheduler is meant to work?
 
Poseidon.library creates its &quot;Poseidon Event Task&quot; during RTF_COLDSTART -&gt; then calls Wait(), and ends up in limbo because wait disables interrupts (used for the scheduler heartbeat), and basically waits forever because the sigbit is never set, since krnSwitch doesn't switch the task unless TF_SWITCH is set, and no codepath run during this seems to set it?? TF_SWITCH does not disable/enable switching. This flag just enables to run user-supplied hook when the task is being switched away. It is completely safe to call Wait() in Disable()d state. Doing this actually temporarily breaks this state. IDNestCnt gets remembered in struct Task, then next task is selected, and its IDNestCnt is restored in sysbase (see kernel_scheduler.c). If there are no other tasks, then your cpu_Dispatch() should enable interrupts on the CPU and enter idle mode. See x86 implementation for good example.

You miss what happens next...
 1. KrnSwitch() saves context of your task, saves IDNestCnt (core_Switch() and cpu_Switch()), then drops into cpu_Dispatch().
 2. cpu_Dispatch() calls core_Dispatch. Then two cases are possible:
 2a. There is a READY task. It is picked up, its IDNestCnt is restored in SysBase, then cpu_Dispatch() needs to restore registers and exit. The next task is run.
 2b. There are no READY tasks. core_Dispatch() returns NULL. In this case your cpu_Dispatch() should enter idle loop. It should just enable interrupts on the CPU and put it on halt. This allows it to process hardware interrupts. Eventually some of your interrupt handlers wakes up your task and puts it into READY list.

My heartbeat interrupt has been slowed atm to help debugging - but it never actually gets a chance to fire because of the Wait() disabling interrupts. Perhaps you have forgotten to enable interrupts in your idle loop.

There is a change in the format of AROS executables. Until now we were using Elf RELocable files which are usually used as intermediate object files. We had them for various reasons, one of them was how AROS files were built in the past. That days we had no real aros cross compiler and the option to embed relocation data in unix executables (or in executable files in general) was rather new and not every linux/unix system had it. Therefore we have decided to use intermediate files. Although it was somehow working (and it is still working :-)), it has some drawbacks. Therefore decided to introduce real Elf EXEC types, in first turn implemented on ARM target with option to expand in future to all other AROS architectures.

The first patch was pretty easy and appeared to work somehow. It generated nice executables with embedded relocation info. Not only that, it also removed all global symbols adjusting relocation data to be relative to the beginning of the sections. That move reduced number of symbols in each executable significantly (depending on the file between 20 and 80% of all symbols could be removed). The only symbols that stayed in the file are local ones - due to the nature of the patch wasn't able to remove them since we have not seen them in the symbol hash table.

The patch didn't worked though. The files were relocated, AROS kernel loaded, but it crashed very early. What happened? Well, the nature of ARM relocations happened :)

Most of the relocation data on all machines is rather simple. Relocation can be absolute or pc-relative, sometimes the offset has to be bit shifted. On ARM v7 there is another one. There, when one wants to load an address of function/variable into register a combination of two instructions can be used: movw and movt. The first one loads immediate into lower 16 bits of a register while clearing upper 16 bits. The second one loads immediate into upper 16 bits without touching lower halfword. Loading of a pointer into a register looks like this:

        movw r0, #:lower16:label

        movt   r0, #:upper16:label

In this case there are two relocations - one for lower halfword and another for upper. If an overflow of lower 16 bits occurs during relocation process, the upper one should be updated as well. Unfortunately with current patch and with typical ARM executables there is not enough information to perform the calculations.

There are two options - the first one would be to give up and go back to &quot;fake&quot; executables, another one would be to change from REL to RELA relocation info. The latter contains an addend, extra data which can be used to perform all the relocation calculations I need.

Decided for the second option. The patch is already in the works. There is another function for the binutils' bfd backend to perform the final relocation. There can decide what to do with every reloc info, modify data and eventually strip some symbols. An advantage is - at this stage of the linking process have also full access to all local symbols so can change all relocations section relative and eventually strip all symbols from the files. 


 GPU 

VCore developed by Alphamosaic Ltd and now owned by Broadcom. Most of start.elf runs on the GPU.   Placing ALL the userland GPU code in the videocore.hidd isn't going to be a terribly big problem because the code they published is nothing more than a shim that sends data straight to the GPU to execute.

The good news about this is that we only need to write our HIDD using the OpenVG API.   The shim is relatively small codewise and lives in the ARM memory (the actual OpenVG code itself lives in the GPU RAM area and its loaded from start.elf).   That's also the bad news.  Our driver has to translate AROS video calls to OpenVG calls, for most tasks it should be easy, for some, not so much.  It's still probably less difficult and less work, than controlling the GPU directly.

The other good news is that anything done through OpenVG happens on the GPU, its truly accelerated.   It also has some nice font functions, meaning we can lead into an accelerated text mode later.

Basically, AROS resets or locks up when it tries to use AROS_ATOMIC_INC or DEC.  If I comment out the byte/word operations in the header files and use non-atomic operations, the code works as expected.
 
have read that the L1 cache needs to be enabled to use LDREX and co (which I also read is only meant to be used on multi processor systems with shared memory) - however I am certain this is correctly enabled.

If you are using LREX or STREX, you should have L1 cache enabled, at least on the ARM CPU I work with at work.

L1 cache is enabled by enabling the MMU *AND* setting the C and I bits in the CPU - the C bit is ignored, and the I bit only covers the 16 byte instruction pipeline if the MMU is not enabled.

Can you verify that your assembly is generating LDREX/STREX? From the behavior, it almost sounds like its generating the default Semaphore locked atomics.
 Impossible. There are no semaphore-locked atomics. There are Disable()/Enable()-based ones instead. And there's a special #define AROS_NO_ATOMIC_OPERATIONS in this case, which tweaks Disable()/Enable() implementations not to recurse forever.
 I have tested this on ARMv5 which does not have ldrex/strex, it works fine. On those ARMs there's no way to have real atomics. On other OSes (like Linux) this is done by introducing things like atomic_t, which appears to be a complex structure, holding the value together with accompanying spinlock (implemented using swp).

    #warning &quot;TODO: lookup optimal mmu table settings for raspi memory&quot;
        /* Set up an identity-mapping for all 4GB */
        for(x = 0; x &lt; 4096; x ++)
        {
            pagetable[x] = x&lt;&lt;20 | (0x40002|0x80000|0x010000|0x00C00|0x04);
        }

Shouldn't there be a second loop that sets the 'C' bit in the descriptor for the RAM pages?

Currently, you have TEX=0, C=0, B=1 for all pages (Shared Device).

You should have TEX=0, C=1, B=0 for RAM (Write-Through, Cached)

    So ..
     
     pagetable[x] = x&lt;&lt;20 | 2;

     
    should be enough?

No, for RAM you need to change the '| 0x40' to '| 0x80'

tell dosboot the correct defaults to use

Please don't do this. This bootconfig.c is a deprecated legacy thing. I wanted it to go away completely with time. Instead,  display  drivers  should auto-install themselves during own initialization phase. I. e. detect hardware=&gt;instantiate itself. This   should   make  things way simpler. With this approach you only need  to add the driver into KS image to get the device autobooted. No hardcoded stuff. 
Currently  VESA  and  VGA drivers do this, look there for examples. never rewrote ATI driver because i don't have any test system for it.

they defined a smaller AROSCPUContext than the ExceptionContext - yet reference it as ExceptionContext in other places, and since it hasn't allocated enough storage for ExceptionContext, are corrupting memory/the structure (since the elements that are there don't map 1 to 1 with the exception context).

AFAIK, AROS has been moving in a different direction to this in recent years. It is the job of graphics HIDDs to allocate bitmaps etc. so that they have the most suitable characteristics, including allocating them from GPU RAM where possible. The concept of chip RAM is only for legacy code, and most if not all non-68k platforms should have all system RAM
marked as chip.

BTW, is the video processing code you mention CPU code or GPU code?

Also, IIRC we have support for &quot;external memory allocators&quot;. Perhaps that's what we need for the allocation of GPU RAM through the mailbox.

All hosted and x86 native ports should use proper context formats.

trying to clarify if the vblank handler has to have run by this point to prevent this deadlock. Actually, no. Unless you have installed VBlank handler which should wake up at some point. Without VBlank there will be no quantum count. Consequently, there will be no forced preemption. But the rest will work, and multitasking will be cooperative (switch happens only when current task voluntarily gives up the CPU). Does it depend on the vblank having run before this point? and if yes what does that mean on systems where it might be able to run enough code (e.g. get to this point) before the vblank interrupt has triggered? What is it waiting for? It could wait for timer, in this case you need timer.device working. VBlank is currently needed for exec's quantum counter. In current native ports we have only a single timer, which is served by timer.device. VBlank is simulated by timer.device also. If your machine has two timers, then you can use one of them for VBlank, and another for timer.device, this will simplify things down. VBlank needs to be 50 Hz for historical reasons, many programs use it as cheap timer. I am periodically thinking about making some abstract mechanism to be able to change quantum source (and untie it from 50 Hz), but have no time to come up with something good. Additionally i started disliking timer.device hardcoded design when PC has got many timers (old 8253, APIC, HPET).
Currently i think there should be some low-level entity representing tick source. timer.device should just select the most appropriate source for its units.
The BCM2835 has 4 GPU based timer sources - 2 are used by the GPU, so im using Timer3 for our heartbeat and the remaining one will be free to the system. There is also the less capable ARM timer but that is dependent on the CPU frequency. Very good. You won't need any emulation. Set the heartbeat to 50 Hz and drive VBlank from it. Use other timer for MicroHZ.

Can you use the 'econsole.hook' I make for debugging the Sam460 via the serial port?
It provides a before-anything-else shell prompt on the serial port.  You can then do 'NewCLI' to test your graphics, or use any DOS command in shellcommands.resource.

You should just be able to add econsole.hook to your module list, and use 'econsole' in your bootargs.

So long as you have a working Exec/RawMayGetChar and Exec/RawPutChar, it should work.

Also make sure to add shell.resource and shellcommands.resource for this.

That should have done it.

If you set &quot;#define DEBUG 1&quot; in  arch/all-native/econsole/econsole.c, do you get any additional serial output?

have added it to the build and added econsole to the command line - and can see the bootloader picks up on the emergency bootconsole tag, but I still only get the insert bootable media display?

Im assuming it exposes a fake filesystem that tricks aros into booting?
The contents of which are: ECON:AROS.boot

Way to handle the scheduling code? The implementations I had been following were causing problems, due to cascading interrupts which I cant handle properly in the asm stubs just now (when they break disable etc.) - since it means detecting the interrupted codes cpu mode and getting the correct sp/lr for it, and that's just too tedious for arm.
 
To work around this ive added a system idle task which does nothing - and when the scheduling code has no task to run switches this in and lets it run, thereby allowing the interrupts etc to resume until something does need to happen.
 
Also, by adding accounting code to cpu_Switch() and cpu_Dispatch(), it should allow the system to log idle time correctly (as well as running tasks).
 
have thought of also adding an additional task that never runs, solely to record time spent in IRQ handlers, but I digress..

was under the impression that kernel.resource should *never* be used outside of exec.library. This is a wrong impression.
Michal started designing it because portable nature of AROS does not fit well into exec's API with all its assumptions. So, he started the new, hardware-agnostic kernel API from scratch. Yes, exec sits on top of it in places. But kernel always meant to be open thing. Otherwise it would not exist. 
it wasn't meant to be just used willy nilly by user code - but by lower system components (e.g. exec) so that they could be implemented in a more generic fashion, and the kernel resource itself hide the systems quirks.

Adding new things there perfectly keeps up with our decision to minimize AROS-specific intervention into APIs which can clash with MorphOS or Amiga OS4 extensions. We want at least source-level compatibility there. Binary compatibility on PPC would be extremely cool, but at the other hand we have no maintainer for this, as well as their ABIs splintering. 
It depends on what exactly is being implemented - there's no reason we should have everything crammed into kernel.resource if it doesn't need to be (i.e. if its better suited as a separate component/subsystem in its own right)

The _LE versions are for when you have endian swapping taking place.  If the graphics are the same endian as the CPU, no swapping should occur.  I ran into a similar terminology problem in SDL with a friend insisting that his Radeon 7000 on his PC was big-endian.  It is not, it just uses the same endianness for the graphics card and the CPU so no swapping was necessary.  They were both little-endian.
The _LE versions are because the PixFmts refer to the bitmap data being in big endian format in memory, for which the normal version would need to do endianness conversion before applying the shifts/masks. on this platform it is in _LE in memory also so we don't need the conversion hence using the _LE version of the call). would use _LE (if it's really little endian 16 bit mode).

 
What is the bare minimum needed to implement a framebuffer based gfx driver, with our software handling the rest?

Have tried with just a gfx class that only expose new/dispose/newbitmap - and having an onscreenbitmap used only for the framebuffer itself (with all other bitmaps being chunkybm, and the framebuffer's superclass also being chunkybm), but that alone isn't enough it seems?
You can use workbench/hidds/sm502/ as your example - it is as simple as I could make it.
So, AROS creates the framebuffer bitmap (verified this) -&gt; so surely it should be capable of then rendeing into it? I don't actually create the framebuffer &quot;bitmap object&quot; myself - only as a result of being asked to. The code I currently have on SVN seems to create the framebuffers bitmap object fine, but then crashes in intuitions DisplayDriver callback.  In particular it crashes performing the getattr on the system default pointer. don't expose MEMF_CHIP in an allocatable form so AllocSpriteData was failing (and other code later doesn't check if the values are valid == illegal memory accesses) 

So far have -:

vc_init: queries the gpus memory, and sets up a fake memory handler for it, then adds the bootmode driver and returns saying all is well
vc_gfxhidd:New: sets up some fake syncmodes to test with and creates the real gfx object.
vc_gfxhidd:NewBitmap: checks if its a framebuffer and uses the onbitmap class or uses the chunkybm class otherwise
vc_onbitmap:New; creates a chunkybm object and then pushes the real framebuffer address into it as the buffer,

vc4 had v8adds, v8subs, v8muld, v8min and v8max which operated on four 8bit uint values packed into a 32bit register. Multiplication was in the range 0.0 to 1.0 and addition/subtraction saturated. There were also a range unpacking/packing modes that allowed you to pack and unpack 8bit values into 32bit registers. 

RasPi has to speak to the &quot;operating system&quot; which runs on the GPU itself and request/free memory - it cant directly manage it itself, and so the managed functions were used to wrap these calls.

The Arm and GPU share memory space. The framebuffer is shared. The Arm can write a pixel and it will appear on the screen (through GPU hardware) without flushing/copying being required.

The GPU can composite multiple FB's in real time - so you have a number of surfaces defined which are rotated etc and  composited in real time to the output. Copying can map from the address space of the Arm to the flat space of the GPU which takes some code, but I don't think whole buffers are copied.

The DMA hardware can also access the whole memory space and can perform 2D fills and blits (no blending). This is documented in the peripheral spec posted. The DMA is just an Arm accessible peripheral and can be set up with low latency (e.g. microseconds).
must use a 0xc0000000-based bus address to access SDRAM, yet non-DMA access should go via a 0x0-based bus address. 
For 2D dma, set TDMODE, and the spec says &quot;interpret the TXFR_LEN register as YLENGTH number of transfers each of XLENGTH, and add the strides to the address after each transfer.&quot; so set STRIDE to pitch of the image, the width is XLENGTH and height is YLENGTH. You would fill by not setting the SRC_INC and point source to your fill data.

The DMA cannot see the ARM's L1 cache, so you would map the framebuffer with ioremap_nocache. Depending on where the source data comes from, it may need an L1 cache flush. The DMA can see the L2 cache. Use 0xC0000000 bus addresses when L2 is disabled and 0x40000000 bus addresses when L2 is enabled. (actually just call virt_to_bus and you'll get the right address out).

openGLES/openVG has high latency. Writing to framebuffer then reading it back is very inefficient (e.g. milliseconds). If you can drive it a unidirectional way, just streaming commands at then that is efficient. openVG is not implemented on top of openGLES - it uses the same hardware but as a first class interface

To improve the Gfx driver, we will need a DMA resource implemented so can use to perform DMA operations. The Gfx driver will need this to perform blits.


Actually MEMF_CHIP has to present, for historical reasons.
This has been never fully agreed upon, but in ports i wrote i exposed the whole memory as MEMF_CHIP. The idea behind this is that CHIP is originally the memory where graphics and sound data can be put. On non-Amiga platforms there are no restrictions on this, so the whole memory is CHIP.
Yes, many old software can misbehave with CHIP memory size larger than 2MB. But this actually applies only to m68k AROS which is going to run m68k binaries. In other cases it's quite logical to fix the program when porting.

As to original question: yes, it's enough to have a framebuffer bitmap (one with aoHidd_BitMap_FrameBuffer set to TRUE) and PutPixel routine. It framebuffer can be served by chunky bitmap class, then you can simply create chunky bitmap with your own buffer (see how VESA driver does this). Chunky PutPixel is already there.

struggling to determine what is the correct pixfmt to use for the 24/16/15 bit gfx modes on the RasPi.  AFAIK it uses RGB565, for 16bit but im unsure what shifts etc should go with it? suffice to say Im getting the wrong colors so far lol.

&lt;pre&gt;
redmask: 0x0000F800
greenmask: 0x000007E0
bluemask: 0x0000001F
alphamask: 0

redshift: 16
greenshift: 21
blueshift: 27
alphashift: 0
&lt;/pre&gt;

It should likely be vHidd_StdPixFmt_RGB16_LE

This stuff is a bit confusing.  The &quot;names&quot; of the stdpixfmts are based on the layout in memory,
ignoring endianess. So for example:

ARGB32: will be 0xAA 0xRR 0xGG 0xBB in memory on both big endian and little endian machines.

The shifts and masks OTOH are based on pixel access (ULONG in this case), so differ depending
on whether you run on big endian machine or little endian machine (that's why there's stdpixfmt_le.h and
stdpixfmt_be.h in rom/hidds/graphics/).

With the 16 bit pixel format it's even more confusing, as for example it's impossible on little endian machine
to describe RGB16 with shifts/masks alone. That's why there's vHidd_PixFmt_SwapPixelBytes_Flag.
(RGB16 == RRRRRGGG GGGBBBBB in memory, and for pixel (WORD) access on little endian machine it needs to
be accessed as GGGBBBBBRRRRRGGGG).

The shifts btw indicate how much to shift the component to the left (!) so that it is moved to the highest bit (31).

The aHidd_PixFmt_StdPixFmt you specify will be ignored most of the time, because when the pixelfmt is registered,
the gfx hidd checks if there's an identical pixfmt (shifts/masks/etc., but ignoring pixfmt-&gt;stdpixfmt) already in the system,
and if so, it uses the already existing one and does not create a new one.

In theory it would be better if gfx drivers could simply/only specify a StdPixFmt without all the shifts/masks stuff when the
gfx driver uses pixfmt which matches one of the stdpixfmts exactly. Another possibility would be for gfx drivers to use
HIDD_Gfx_GetPIxFmt(stdpixfmt_gfx_driver_wants_to_use) and then peek shifts/masks from it and fill out a pixfmt
tag list based on that.
15bit very blue/green: Try to pass same shifts/masks/etc. as in 16 bit pixfmt (maybe you think it's using 15 bit R5G5B5
(or swapped) but it's actually still using 16 bit R5G6B5 (or swapped).
 aHidd_PixFmt_StdPixFmt you pass is mostly ignored. It's the shift/masks/etc. that count.
But I would still pass the correct one (_LE) == whatever rom/hidds/graphics/stdpixfmts_??.h uses
in the entry where you have looked up shifts/masks/etc.

Use the shifts/masks/etc. from the entry in stdpixfmt_le.h (if you are running on little endian machine) or stdpixfmt_be.h (if you
are running on little endian machine) that matches the pixfmt that its meant to be.

0xAA,0xRR,0xGG,0xBB on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on little endian (-&gt;entry in stdpixfmt_le.h which says vHidd_StdPixFmt_BGRA32)

0xAA,0xRR,0xGG,0xBB on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_ARGB32)
0xBB,0xGG,0xRR,0xAA on big endian (-&gt;entry in stdpixfmt_be.h which says vHidd_StdPixFmt_BGRA32)

it feels like AROS trashes the alpha component, otherwise it should be 8A8R8G8B.

read on the subject suggest its in 1x5r5g5b (x is ignored) to keep 16bit alignment .
 
Suggests to me that wrong shift/mask are being applied - however going by the 16bit versions it all looks correct to me so I am really confused as to what is happening.

The output image looks to have too much green/blue, and very weak red.


 Kickstart 

The  idea  is  to minimize amount of archirecture-specific modules to make the user's  life  easier.  So,  the kickstart was split into 'base' (which  does  not  contain anything machine-specific) and 'BSP' (Board Support Package) which contains all hardware-specific stuff. This  way,  for  example, distribution makers can save up space on CD and  make  CDs with multiple platform support. Different configuration would load the same base with different BSP's.

Next  there  was some part which is entirely missing on hosted. These are   filesystems.  Hosted  ports  do  not need them to boot up, so on hosted   they  are  left  out.  At  the  other  hand,  they  are  also architecture-agnostic.  So  i put them into 'FS' package (standing for 'filesystem').


 USB 

Poseidon  is  one  more  big part. I made it into separate package in order to allow users to omit it if they don't need it (for example, to run  on retro PCs without USB). Personally i have one. Again, Poseidon is  hardware-agnostic (well, there are USB drivers but HCIs are pretty standard).

AFAIK its HCI 1.0 compliant but not familiar enough with poseidons drivers, nor USB, to just hack away at the existing code.  Perhaps once i'm more familiar with the workings I can merge in the changes needed to get it operating but for now I will focus on getting it running.  Also our drivers have known issues so perhaps a fresh set of eyes might shed some light on what is going wrong.

Another interesting question is whether Poseidon can operate on device side. Is it flexible enough? How similar is being a USB host and USB device? think it will need a bit of work on Poseidon's side.  Until then I will force the driver into Host/Master mode in the init code, but leave open device etc to configure the chipset for either's use - and look at trying to add support for working in Device/Slave mode &amp; switching modes once it's up and running.

Actually USBROMStartup is some kind of kludge. Can there be any alternative? Could device drivers be self-installing, like our HIDDs? This would get rid of need to list them in USBRomStartup.

* Model A and B limited to 150 mA per port. 
* Model B+ and Pi 2 introduced configurable 600 mA to 1.2 A support over all ports - anything above that requires a powered USB hub.

Implementing the hardware driver that Poseidon uses to interact with the USB components.

Have code in place to (try) and initialise the USB chipset, and configure host/device mode operation (though AFAICT Poseidon doesn't support device mode). Started to get the &quot;virtual&quot; root hub written for the single USB port so that Poseidon should at least list it correctly in the GUI - and try to interact with it to find peripherals.


The BCM2835 uses a soft IP block from Synopsys’ DesignWare library (DWC), specifically the block is called dwc_usb_2_0_hs_otg_subsystem-ahb_se (“USB 2.0 Hi-Speed OTG Controller Subsystem w/AHB Interface SE”).

There is no public documentation for this, and pretty much zero chance of anyone getting hold of it even with NDA. However, there's a Linux driver written by Synopsys ([https://github.com/raspberrypi/linux dwc_usb]). Specifically directories [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_common_port] and [https://github.com/raspberrypi/linux/tree/rpi-patches/drivers/usb/host dwc_otg].

The Synopsys code is actually under a fairly permissive licence – it's not GPL, it's similar to BSD (’don't sue us if it breaks’ is pretty much the only clause). So this should not be a barrier to porting the code.

The code is really well written, with a nice partition between the work done by the driver (dwc_otg, which is fairly involved, given the host does more work than a conventional EHCI driver), and the interface to Linux (dwc_common_port).

Probably only need provision of relevant changes to dwc_common_port. Other things to consider....

* Provision of necessary headers to get it to compile
* Provision of necessary functions (main issues are wait queues, threads, work queues, tasklets, timers, spinlocks and mutexes (multithreading) )
* Interfacing between USB stack and the driver. dwc_otg/dwc_otg_hcd_linux.c looks like the place to start.

the Linux bits of the headers are only required for the dwc_common_port library. dwc_common_port includes a variety of crypto functions which are not used – it appears to also be used for ultrawideband (UWB) and wireless USB (WUSB) drivers where crypto will be an issue, but it isn't going to be for plain wired USB.

Every USB driver acts as an USB hub as well in order to let Poseidon control the state of USB ports. The code there was reading status of the only USB port in Raspberry's CPU but when changing the status it erroneously deleted some of the status bits, including the port enable one. It was so because those bits in the status register are of a type Read/WriteToClear. It means, if one does not want to change their value from 1 back to 0, one has to actually write the 0 value. Very practical thing e.g. in interrupt handlers, where one reads the interrupt status register to learn what was the interrupt reason, and writes it back to the same register in order to clear the interrupts. 

After fixing that code it turned out that the communication was still unsuccessful. Apparently the USB device was not understanding the host for some reason. That should not happen since the request sent was one of the standard ones implemented by virtually anything with an USB connector, assumed that Poseidon clears the data caches before forwarding the work to the USB drivers but that's the responsibility of the driver itself. 

The USB device responded and acknowledged the transmission! But why were all the request sent after address change failing with timeout? They should not. Once again, address set is supported just by anything. Tried to contact the device at address 0 once again and there it was, still responding properly. The enlightenment came. The bus address for DMA transmissions was, as it is in many bare metal USB implementations, just the pure memory address of the buffer as seen by the ARM cpu. Have &quot;prefixed&quot; it with the real location of uncached RAM and booted AROS once again. 


Trident saw this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

and this:

    Product     : Vendor: Vdr=0424/PID=EC00
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 255
    SubClass  : 0
    DevProto  : 1
    VendorID  : 1060
    ProductID : 60416
    DevVers   : 0200

and even this:

    Product     : Hub: Vdr=0424/PID=9514
    Manufacturer: Standard Microsystems Corp.
    SerialNumber: n/a
    /Users/michal/git/AROS/rom/USB/poseidon/./poseidon.library.c:psd_20_psdEnumerateDevice/3092: USBVersion: 0200
    Class     : 9
    SubClass  : 0
    DevProto  : 2
    VendorID  : 1060
    ProductID : 38164
    DevVers   : 0200

What are these things? The first one is USB hub built in the Raspberry. Thanks to this one the Pi machines (with exception of Pi0 and computing modules) have more than just one single USB port. The second one is the network chip in raspberry, the third one is my USB SD card reader which have just connected to see what happens. AROS tried, of course, to boot from it ;)

So, the first step towards working USB is done. The control transfers are working as you can see above. Next step is to implement bulk and interrupt transfers, having the basics in place. Finally some error handling will be added and USB for Pi will be as complete as the PC version. 

[http://www.raspyfi.com/raspberry-pi-usb-audio-fix/ Issue with USB Audio]


 Audio 

[https://github.com/raspberrypi/linux/tree/rpi-patches/sound/arm audio] and its [https://github.com/raspberrypi/firmware/issues/2 very high speed message passing interface type of thing VCHI]

The Model B+ added an additional voltage regulator for the audio output and an additional output driver to drive low-resistance loads like headphones. However it is still using pulse-width modulation (PWM), which has a major impact on sound quality

the old Raspberry Pi used a linear voltage regulator to provide the 3.3V to many of the components on the board while the new one uses a switching regulator. Both can perform reasonably well. However switch mode power supplies often show higher noise figures

Analogue audio

Audio over HDMI rev 1.3 &amp; 1.4


 Ethernet 

10/100 BaseT Ethernet RJ45 socket


 GPIO 

GPIO shouldn't be too bad but bear in mind it is already accessed in places so they would need to allocate pins etc through it (e.g. sdcard to flicker the activity light, serial debug to output data on the GPIO pins)

Probably a resource rather than a device...

Started an i2c driver that will need to allocate GPIO pins. Feel free to work on it if you are interested ;p


 GPU graphics with 2D and 3D acceleration 

Sadly none yet for 32bit but for 64bit... 


 Miscellanous

hdmi issues

Setting the hdmi_force_hotplug=1 makes sure the Pi believes the monitor/TV is really there.

You might also need to set config_hdmi_boost=4 or even higher (up to 9) if your display needs a stronger signal.

If the display is a computer monitor or newer tv, use hdmi_group=1 (auto HDMI use) and if it is an older TV, try hdmi_group=2 (for DMT formats, i.e. for PC monitors) then you HAVE to &quot;set hdmi_drive = 2 to enable HDMI output as this forces HDMI mode rather than DVI mode

Do not set hdmi_safe=1 as that overrides many of the previous options.

Using a shorter or better quality HDMI cable might help. Make sure your Pi's power supply delivers 1 A and not 500 mA.
If you see a problem with the red colour - either absent, or interference - then try a boost

composite video

changing the RCA cable, then the composite port worked out of the box

Boot it as you are doing, without HDMI. If you now plug in the HDMI, do you get the image? In other words, does the Pi think HDMI is connected even when it isn't?

Rename all the files in the first partion of the card except bootcode.bin, start.elf and fixup.dat  What's the result?

Put back config.txt What's the result?

for PAL mode   sdtv_mode=2

dmi_ignore_hotplug Pretends HDMI hotplug signal is not asserted so it appears a HDMI display is not attached
hdmi_ignore_hotplug=1 Use composite mode even if HDMI monitor is detected

&lt;pre&gt;
# NOOBS Auto-generated Settings:
#hdmi_force_hotplug=1
#config_hdmi_boost=4
#overscan_left=24
#overscan_right=24
#overscan_top=16
#overscan_bottom=16
#disable_overscan=0
start_x=1
gpu_mem=128
&lt;/pre&gt;

tvservice -c &quot;PAL 4:3&quot;

&lt;pre&gt;
/opt/vc/bin/tvservice -s   or tvservice -s 
state: HPD high|HDMI mode|HDCP off|composite off (0x12001a), 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m CEA
Group CEA has 1 modes:
(native) mode 16: 1920x1080 @ 60 Hz, progressive

/opt/vc/bin/tvservice -m DMT
Group DMT has 0 modes:
&lt;/pre&gt;

sudo amixer cset numid=3 1

forces the audio to the headphone jack, even with the HDMI video output plugged in

config.txt

the hdmi_ignore_edid_audio=1 option sems relevant as it should tell ALSA that the only available audio is analog, no matter what the display says

There are several different ways that these 4 pole (ring) composite analog cables can be wired up, so some work great in some applications and can be a waste of time in others.

What is needed for the Raspberry Pi B+ and above, which like many camcorders needs the ring contact next to the base contact to be the ground.


The wiring for the 4 pole are:

TIP (LEFT AUDIO CHANNEL)

RING 1 (RIGHT AUDIO CHANNEL)

RING 2 (GROUND/EARTH)

RING 3 BASE/SLEEVE (VIDEO) YELLOW

Most Apple based Players and the Microsoft Zune (TM) are wired this way.

Most analogue camcorders are wired this way as well, where the ground in on Ring 2 will work with the Pi although you may need to swap your Video plug with the Right Audio plug.

Nearly all other MP3 players are not wired this way, the ground is on another ring ie the wrong one.


External devices

* Camera Module Omnivision ov5647 Sunny 5MP (NoIR version) V1.3 - NoIR at 850&amp;nbsp;nm, peak at 880&amp;nbsp;nm and trails off at 940&amp;nbsp;nm wavelengths 
* Camera V2 Sony IMX219 V2.1 8mpixel 8MP 8megapixel - 3280 x 2464 pixels - video at 1080p30, 720p60 and 640x480p90 - wider field of view, 62 vs 54 degrees horizontally - 
* Branded WIFI usb BCM43143 dongle

N.B.  dreaded error after changing cameras (stupidly without turning off the power first) and lasted through several power cycles.  It can be a bad 15-pin FFC ribbon cable, when swapped, camera(s) and the Pi itself are working OK. It can be an instance of a cold solder joint on the CSI connector on the pi board.  the camera can be detected (that's done via I2C) but may still not be able to receive image data (done via CSI-2) if something is broken. CSI-2 is uni-directional. Control is generally done via I2C. 
The CSI-2 receiver always writes to memory, not direct to the ISP. That's the way the Broadcom architecture works as it allows multipass processing easily. GPU memory is accessible from the ARM. Processing using the QPU graphics processors may be possible.  currently the only supported sensor is OV5647 and IMX219.  The linux drivers are all in the firmware blob, else you'd  be looking at at least a man-month of work in a fully fledged imaging lab to do a decent tuning of the camera modules' ISP parameters. 
Static electricity maybe an issue for the camera module and slightly less for the pi board.


== References ==

[https://www.raspberrypi.com/documentation/computers/compute-module.html CM5] has the same 55mm x 40mm 2x100pin connectors form factor as the CM4 but [https://www.epdtonthenet.net/article/214508/Key-Considerations-When-Migrating-from-Raspberry-Pi-CM4-to-CM5.aspx some pins and other small things] have changed. Will need the [https://raspipcb.com/tech-blog/raspberry-pi-cm4-vs-cm5-difference-in-booting-from-sd-card/ right IO board to suit] 

*Green [ Raspberry Pi Compute Module 5 IO Board REV2 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1967]] - untested 
*Green [ RPi Compute Module 5 IO board REV1 [https://pip.raspberrypi.com/categories/1097-raspberry-pi-compute-module-5-io-board SC1751]] - untested 
*Black SupTronics Geekbord X1500 CM5 IO Carrier Board - untested
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[https://sipeed.com/nanocluster Sipeed NanoCluster] - untested up to 7 CM5 
*Green BentoIO CMX0 - untested 
*Box EDATec ED-CLAWBOX - untested 
*Home Assistant Yellow - Kit with PoE with Raspberry Pi Compute Module 5 - untested 
*Blue [https://www.waveshare.com/wiki/CM5_PoE_BASE_A Waveshare CM5-PoE-BASE-A] - untested 
*Box  Waveshare [ CM5-POE-BOX-A] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-B Waveshare CM5-IO-BASE-B] - untested 
*Blue [https://www.waveshare.com/wiki/CM5-IO-BASE-A Waveshare CM5-IO-BASE-A] - untested 
*Blue Waveshare [https://www.waveshare.com/wiki/CM5-NANO-B CM5-NANO-B] - untested 


*[https://carboncomputers.us/products/pi-flux piFlux]
*[https://carboncomputers.us/products/ Zitaotech Hackberry] CM5 lite only - 
*Portable [https://www.waveshare.com/pocketterm35.htm Waveshare PocketTerm35] with Pi4B or Pi5 - untested 
*Box [https://www.clockworkpi.com/uconsole ClockworkPi uConsole][https://www.youtube.com/watch?v=EtI_bAahbR8 CM4 into an adapter or CM3 into so-dimm - Cyberdeck] - untested 


*Green RPi [https://datasheets.raspberrypi.com/cm4io/CM4IO-KiCAD.zip Compute Module 4] [https://datasheets.raspberrypi.com/cm4io/cm4io-datasheet.pdf IO board] V1.4 [https://datasheets.raspberrypi.com/cm4io/CM4IOUSB3-KiCAD.zip USB3] [https://datasheets.raspberrypi.com/cm4io/cm4iousb3-appnote.pdf CM4ISO] [https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf Dual100pin] (2020) aka Development Platform Board - untested 
*Purple Pi Hut Cytron CM4 Maker Board - untested 
*Black DeskPi Super6C Cluster Mini-ITX Board - untested 
*[ KubeSail PiBox mini 2] 
*Home Assistant Yellow with Raspberry Pi Compute Module 4 - untested 
*[ Turing Pi V2] - untested CM4 with 260-pin SO-DIMM socket adapters and/or nvidia jetson nanos - untested 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-B Waveshare CM4-IO-BASE-B] - untested but binary blobs 
*Blue [https://www.waveshare.com/wiki/CM4-IO-BASE-A Waveshare CM4-IO-BASE-A] - untested but binary blobs 


CM3 has a 200 pin sodimm ddr2 connector form factor but not electrically SC0028, SC0029 
*Blue [https://wiki.geekworm.com/CM_IO_Board Geekworm RPi Compute Module IO Board] [https://github.com/geekworm-com/cm-io-board CSI DSI] with CM3 in ddr2 slot underside - '''works''' if SW1 on but CM3+ '''does not''' 
*Green [https://cdn-shop.adafruit.com/product-files/3442/CMIO_schematic.pdf RPi V3 IO board CM3IO] and CM3 Lite - untested 
*Green [https://turingpi.com/ turingpi v1 cluster] - untested up to 7 cm3 7xlan9514 12V discontinued, 3 x Pi4 homelab maybe better 
*Blue [https://www.waveshare.com/wiki/Compute_Module_PoE_Board Waveshare Compute Module PoE Board] and CM3 lite (if not lite, write files to internal eMMC fat32) '''AVOID''' bin blobs 
*Blue [https://www.waveshare.com/compute-module-io-board-plus.htm Waveshare Compute Module IO Board Plus] [https://www.waveshare.com/wiki/Compute_Module_IO_Board_Plus wiki] [https://forums.raspberrypi.com/viewtopic.php?t=235695 pin settings] with CM3+ Lite - '''AVOID''' binary blob 


*[ Pi02w on Geekworm SupTronics X305 Raspberry Pi Zero IO Baseboard] - untested 
*[ Spotpear Pi Zero 2w to Pi3b format-ish] - untested 


*[ pi-top v4] box has 128x64 oled display, micro hdmi, 19Whr battery with pi4 and 15V PD 36W min needed 
*[ pi-top v3] three green pieces, heatsink covers most of the base tray, pi-top hub mk1 lhs and Pi1B Pi2b Pi3b rhs secured from below, black rounded strip with pi-top above keyboard, 13.3&quot; HD 1366 x 768 display, small touchpad, 
*[ pi-top Model 2.0] pi-top on bottom bezel of 14-inch green laptop, large trackpad, keyboard slide down to reveal main system hub on slide rails moved to the right, Raspberry Pi3b screws down, hub slides in, 18V 2.5A 45W charger brick, battery 11.1V 3500mAh 38.85Wh and storage PiTopOS 
*[ Pi-Top CEED Raspberry Pi Modular Educational Desktop with RPI3] monitor 
*[https://www.indiegogo.com/en/projects/jesselozano/pi-top-a-raspberry-pi-laptop-you-build-yourself Pi-Top v1] wedge laptop with RPi2 


&lt;pre&gt;
2008 Trustees collected for Foundation
2009 Pi Foundation charity status gained 
2010 
2011 First Raspberry prototypes 
2012 First boards go on sale at CPC and RS. The Model A and B 700 MHz Arm11 - February 29th BCM 2835
2012 First million sold - more than the 10,000 original planned and anticipated 
2013 First Alpha Experimental builds of AROS Native for the 32bit Pi 
2013 Pi Trading launched making grants available, providing in house educational resources and Pi Academy for teacher training 
2013 Over two million sold 
2014 Over three million sold 
2014 Pi 1 Model B+ introduced that moved composite video to audio jack and same half gig of memory 
2014 Pi Model A+ v1.1 no ethernet and 1 usb - a little smaller - 
2015 Over four million first gen pis sold  
2015 Pi Zero 1.2 BCM2835 first production revision released with no camera port 
2016 Pi0 1.3 released with camera csi connector 
2017 Pi Zero W v1.1 1GHz Pi0W, single-core 32bit CPU BCM2835 released with Cypress CYW43438 wireless 
2020 Raspberry Pi Pico SC0919 with RP2040 32-bit 2Core ARM Cortex-M0+ up to 133 MHz - 264KB of SRAM and 2MB of on-board QSPI Flash - 
2024 Raspberry Pi Pico 2 with RP2350 2Core 32bit Arm Cortex-M33 and 2core open-hardware [https://github.com/wren6991/hazard3 Hazard3 RISC-V] 

2015 Pi 2 Model B v1.1 BCM2836 900/600 MHz ARM Cortex-A7 Armv7 quad 32bit, 32bit VideoCore IV GPU - 1Gb RAM - 5V 2A micro usb - SMSC LAN9514 chip - 
2015 Over a million pi2s sold 


2015 Raspberry Pi 2 Model B version 1.2 Pi2bv1.2, aka Pi2B2 has armv8 BCM2837 underclocked to 900Mhz without wifi/bluetooth module 
2016 Pi 3 Model B - Broadcom BCM2837 SOC four 64bit ARMv8 Cortex-A53 1.2GHz 32bit 1080p VideoCore IV GPU - 1Gb DDR2 - bluetooth 4.1, Cypress CYW43438 wireless 802.11n - 4 x USB2.0 ports - 5.1V 2.5A - SMSC LAN9514 chip 
2016 PIs total over 10 million worldwide 
2017 Compute Module 3 CM3 with BCM2837B0 armv8 Quad 64-bit - small 67.6mm x 31mm board which fits DDR2 SODIMM connector but not electrically compatible which plugs into needed IO board - beware of the I2C protocol issue 
     1Gb LPDDR2 RAM - Lite or 4Gb Emmc storage 
2017 12 million pis sold in total 
2018 Pi 3 Model B+ - 4c A53 BCM2837B0 1.4Ghz - 1Gb, wireless 802.11ac, gigabit ethernet (300Mbit/s) and bluetooth 4.2 - power over ethernet - 4 x USB2.0 ports - Microchip LAN7515 chip 
2019 Over 15 million sold 
2019 Pi 3 Model A+ with BCM2837b0 Cortex-A53 64-bit SoC @ 1.4 GHz with 512Mb LPDDR2, 1 usb2, 1 hdmi, 1 micro usb 5V 2A - no ethernet - 
2019 Raspberry Pi Compute Module 3+ CM3+ - Broadcom BCM2837B0 1.2Ghz, Cortex-A53 (ARMv8) 64-bit SoC on DDR2 SODIMM mechanically compatible only factor - IO board required 
     1Gb DDR2 and 8GB, 16GB, 32GB or a Lite variant without eMMC 
2021 Pi zero 2 (w or no W) RP3A0 quad 1GHz Cortex-A53 64bit BCM2710A1 512mB SDRam 
2025 edaTEC CM0 ED-CM0NANA with additional dev board with quad 1Ghz A53 with 512Mb Raysan RAM, 2 USB2 and 10/100 ethernet - pico castellated edge
 

2019 Pi 4 Model B RPI4B - BCM2711B0T quad 64bit A72 1.5GHz, 4K VideoCore VI, AC wifi, Bluetooth 5.0, GbE Broadcom BCM54213PE (PHY ID 0x600d84a2), 2 micro hdmi decode up to 4K, USB-C 5.1V 3A power, 2xVLI VL805 USB 3, 2xUSB 2.0, 2GB 9LDWW D9WHZ or 4GB 9FDWW D9WHV, 8GB 0AA47 D9ZCL ddr4 ram 
2020 Silent Pi 4 v1.2 upgrade with more USB-c psu support 
2020 PI400 BCM2711C0T 1.8GHz 4Gb DDR4 inside keyboard, 5.1V 5A 27W usb-c psu, 2 micro hdmi, external ide style 40pin gpio, no audio port - 
2020 Raspberry Pi Compute Module 4 BCM2711B0T on new 55mm x 40mm 2x100 pin form factor with extra breakout IO board 
     CM4101000 1Gb RAM Lite SOM 
     CM4102000 2GB RAM Lite 
     CM4104000 4GB RAM Lite 
     CM4004008-4GB-RAM 8GB-EMMC SOM System on Modules 
     CM4104032 4GB RAM 32GB emmc 
     CM4108000 8GB RAM Lite 
     CM4008016 8GB RAM 16Gb eMMc
2021 Raspberry Pi SC0763 Compute Module 4S CM4S with ddr2 sodimm pinouts but not electrically the same with suitable IO board extra cost - 
     CM4S01000 1GB RAM Lite
     CM4S01008 1GB RAM 8GB eMMC Flash
     CM4S02000 2GB RAM Lite
     CM4S04000 4GB RAM Lite
     CM4S08000 8GB RAM Lite 
2021 Pi 4 v1.4 BCM2711B1 upgraded power regulator, to deal with 8gig of ram being more power hungry - 
2021-48 Raspberry Pi 4 model B v1.5 2GB 


2023 Pi 5 v1.0 BCM2712 Quad A76 @2.4Ghz - VideoCore VII - no audio socket - dual 4k from mini hdmi - fan connector - 5.1V 5A psu 
2024 Pi 5 2GB DDR4 version uses BCM2712D0 
2024 Pi-500 with 8Gb LPDDR5 and membrane keyboard 
2024 Pi 5 v1.1 
2024 Raspberry Pi Compute Module 5 CM5 BCM2712 55mm x 40mm form factor with additional IO board 
     CM5004000 04GB RAM 0GB eMMC Lite
     CM5008000 08GB RAM 0GB eMMC Lite
     CM5016000 16GB RAM 0GB eMMC Lite
2025 Pi-500+ with 256GB NVMe storage, 16GB LPDDR4 RAM, and Gateron KS-33 Low Profile Blue mechanical keyboard switches 
2025 Pi5 1GB DDR4 announced 


2022 PiOS linux goes 64bit 
2024 Pi Trading IPO stockmarket stock exchange listing 


2026 April and May Aros 64bit fixed, added AHI audio, VC4 gfx started, usb functions added to rom  
2026 June and July Aros 64bit usb2otg started, dma.resource, sdio.resource, bwfm.device wifi added 
2026 Late July daily 64bit Pi3 LE little endian builds start 
2026 August Pi 4, 400, 5 and 500 DTBs added, expanding existing support and wifi for Pi4 and Pi5 
2026 August Pi5 HAT+ nvme and HDMI, AHI RPiI2S added, Pi4 HVS5 video scaler started, 
2026 
2027 


2028 Pi 6 
&lt;/pre&gt;


==Future==


[https://github.com/ARMSX2/ARMSX2 Arm pi of pcsx2] 


{{BookCat}}</text>
      <sha1>rgibi6hd8lrupm02vekgzp20q494uxs</sha1>
    </revision>
  </page>
  <page>
    <title>Breton/Level 4</title>
    <ns>0</ns>
    <id>360078</id>
    <revision>
      <id>4669865</id>
      <parentid>4664745</parentid>
      <timestamp>2026-09-13T09:22:46Z</timestamp>
      <contributor>
        <username>CommonsDelinker</username>
        <id>49843</id>
      </contributor>
      <comment>Replacing 26-04-2005-015.jpg with [[File:Brest_-_Vue_du_pont_de_Recouvrance_a_gauche_le_chateau,_a_droite_la_Tour_Tanguy_26-04-2005-015.jpg]] (by [[:c:User:CommonsDelinker|CommonsDelinker]] because: [[:c:COM:FR|File renamed]]: old name is not meaningful).</comment>
      <origin>4669865</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3716" sha1="11n2j9h7ctp19vt6gzx9nalk1zhqjfc" xml:space="preserve">__NOTOC__ __NOEDITSECTION__
{| cellpadding=&quot;10&quot; cellspacing=&quot;5&quot; style=&quot;width: 99%; background-color: inherit;color:inherit; margin-left: auto; margin-right: auto&quot;
| style=&quot;background-color: #f7ff3c;{{Text default color}}; border: 1px solid #777777; -moz-border-radius-topleft: 8px; -moz-border-radius-bottomleft: 8px; -moz-border-radius-topright: 8px; -moz-border-radius-bottomright: 8px;&quot; colspan=&quot;2&quot; |&lt;br /&gt;
&lt;div style=&quot;text-align: center;&quot;&gt;[[Image:Gwenn_ha_du.svg|100px]]&lt;big&gt;&lt;br /&gt;&amp;nbsp;&lt;br /&gt;'''Brezhoneg Pevar'''&lt;/big&gt;&lt;br /&gt;&lt;br /&gt;
[[Image:Brest - Vue du pont de Recouvrance a gauche le chateau, a droite la Tour Tanguy 26-04-2005-015.jpg |800x300px| Port of Brest]]&lt;/div&gt;
|-
| style=&quot;width: 60%; background-color: #fffff0;{{Text default color}}; border: 1px solid #777777; vertical-align: top; -moz-border-radius-topleft: 8px; -moz-border-radius-bottomleft: 8px; -moz-border-radius-topright: 8px; -moz-border-radius-bottomright: 8px;&quot; &lt;!--rowspan=&quot;2&quot;--&gt; |
&lt;div style=&quot;text-align: center;&quot;&gt;&lt;big&gt;&lt;b&gt;Brezhoneg&lt;/b&gt;&lt;/big&gt;&lt;/div&gt;
[[Image:Bretagne Finistere CapdelaChevre 190046.jpg|200px|right|thumb|Beg ar c'havr, Kraozhon]]
==Brezhoneg Pevar==
'''&quot;Brezhoneg Pevar&quot;''' is the fourth level in the Breton course. In this Beginner's course, students are introduced to simple texts, grammar complements and some phrases for a simple conversation.&lt;br /&gt;


|  rowspan=&quot;2&quot; style=&quot;width: 40%; background-color: #efefff;{{Text default color}}; border: 1px solid #777777; vertical-align: top; -moz-border-radius-topleft: 8px; -moz-border-radius-bottomleft: 8px; -moz-border-radius-topright: 8px; -moz-border-radius-bottomright: 8px;&quot; |
&lt;div style=&quot;text-align: center;&quot;&gt;&lt;h2&gt;Breizh&lt;/h2&gt;&lt;/div&gt;&lt;br /&gt;
&lt;div style=&quot;text-align: center;&quot;&gt;[[Image:PhotoGorsedd.jpg|200px|thumb|Gorsedd in Brittany]]&lt;/div&gt;&lt;br /&gt;&amp;nbsp;&lt;br /&gt;

[[w:Breton literature|Breton literature]] In the 19th century antiquarians and Celtic revivalists undertook the collection of folk texts, songs and stories. Writers such as [[w:Anatole Le Braz|Anatole Le Braz]] and [[w:Théodore Hersart de la Villemarqué|Kervarker]] brought new readers to traditional Breton literature.

The poet [[w:Jean-Pierre Calloc'h|Yann-Ber Kalloc'h]] (1888-1917) was killed during the First World War. His posthumously-published collection ''Ar en deulin'' established his reputation as a war poet.

In the 1920s a movement, in which the linguist and author [[w:Roparz Hémon|Roparz Hemon]] played an important part, arose to introduce the trends of modern literature into Breton. The literary magazine [[w:Gwalarn|Gwalarn]] provided an outlet for modern authors, such as [[w:Jakez Riou|Jakez Riou]] and [[w:Yves Le Drézen|Youenn Drezen]] (who published the first long novel in Breton in 1941).

[[w:Pierre-Jakez Hélias|Per-Jakez Helias]] (1914-1995) wrote prose and poetry in both Breton and French. His contemporary [[w:Añjela Duval|Añjela Duval]] (1905-1981) wrote poetry reflective of her peasant origins, mysticism, and social conscience.
&lt;div style=&quot;text-align: center;&quot;&gt;&lt;!--[[Image:Bagad-lann-bihoue1.JPG|300px|Bagad Lann-Bihoue]]--&gt;&lt;/div&gt;

|-
| style=&quot;width: 60%; background-color: #f7ff3c;{{Text default color}}; border: 1px solid #777777; vertical-align: top; -moz-border-radius-topleft: 8px; -moz-border-radius-bottomleft: 8px; -moz-border-radius-topright: 8px; -moz-border-radius-bottomright: 8px;&quot; |
[[Image:Nuvola apps edu miscellaneous.svg|right|96px]]
==Lessons==
*  Kentel kentañ: '''[[/Lesson 1| Poems and Rhymes ]]'''
*  Eilved kentel: '''[[/Lesson 2| In Town ]]'''
*  Teirved kentel: '''[[/Lesson 3| Plurals ]]'''
*  Pederved kentel: '''[[/Lesson 4| More Tenses]]'''
*  Pempved kentel: '''[[/Lesson 5| Jokes]]'''


|}

{{BookCat}}
[[{{BOOKCATEGORY}}/Level 4|*]]</text>
      <sha1>11n2j9h7ctp19vt6gzx9nalk1zhqjfc</sha1>
    </revision>
  </page>
  <page>
    <title>Wikijunior:Stories</title>
    <ns>110</ns>
    <id>384152</id>
    <revision>
      <id>4669832</id>
      <parentid>4657778</parentid>
      <timestamp>2026-09-13T06:37:57Z</timestamp>
      <contributor>
        <username>Ziv</username>
        <id>3267536</id>
      </contributor>
      <comment>→ File has been renamed on Commons ([[:c:GR]])</comment>
      <origin>4669832</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1541" sha1="np82v3dokvihcfi8bnngt1fdjg8hnfw" xml:space="preserve">{{{{BOOKTEMPLATE}}/Header|subtitle=from any time and place}}
__NOTOC__
&lt;noinclude&gt;&lt;div style=&quot;background-color:#bbffaf;{{Text default color}};&quot;&gt;
&lt;div class=&quot;center&quot;&gt;
==Welcome to [[Wikijunior]] Stories==
&lt;/div&gt;
&lt;gallery mode=&quot;packed-hover&quot; heights=&quot;160&quot;&gt;
File:Master of Guillebert de Mets (Flemish, active about 1410 - 1450) - Saint George and the Dragon - Google Art Project.jpg
File:BitvaLincoln1217.jpg
File:Firdawsi - Rustam Kills a Dragon (the Third Feat) - Walters W60276B (cropped).jpg
&lt;/gallery&gt;

This book is a collection of stories, from many times and places and cultures.

The aim of the project is to create a collection of teaching stories for kids; usually short traditional stories with a moral. Shorter versions of the stories are preferred. Typically stories should be a few hundred words; occasionally less than two hundred, rarely more than a thousand.

You are encouraged to narrate a story. If you would like to do so, &lt;!-- please read the [[/Contributing/]] page and --&gt; add your name to the [[/Authors/]] list. 
&lt;/div&gt;
&lt;div class=&quot;center&quot; style=&quot;background-color:#affff1;{{Text default color}};&quot;&gt;
==List of stories==

&lt;gallery mode=&quot;packed-overlay&quot; heights=&quot;170&quot;&gt;
File:Stone_masonry_in_China.jpg|[[/The Stonecutter/]] {{stage short|100%}}
File:Omar the Tentmaker (1922) 1.jpg|[[/Three School Friends/]] {{stage short|50%}}
File:Crimson seedless on the vine.jpg|[[/Quarreling Over Names/]] {{stage short|75%}}
&lt;/gallery&gt;

&lt;/div&gt;&lt;/noinclude&gt;

{{Shelves|Wikijunior Our World of People}}
{{Alphabetical|S}}
{{Status|25%}}</text>
      <sha1>np82v3dokvihcfi8bnngt1fdjg8hnfw</sha1>
    </revision>
  </page>
  <page>
    <title>Wikijunior:Stories/Quarreling Over Names</title>
    <ns>110</ns>
    <id>384180</id>
    <revision>
      <id>4669833</id>
      <parentid>3220948</parentid>
      <timestamp>2026-09-13T06:38:26Z</timestamp>
      <contributor>
        <username>Ziv</username>
        <id>3267536</id>
      </contributor>
      <comment>→ File has been renamed on Commons ([[:c:GR]])</comment>
      <origin>4669833</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1228" sha1="l65slvivgr8eis8bnwh4hzc3lb6ky0n" xml:space="preserve">{{{{BOOKTEMPLATE}}/Header|subtitle=The argument of four persons over grapes, which each one had understood by a different name}}
[[File:Crimson seedless on the vine.jpg|thumb|Grape]]

Back in the thirteenth century in the city of Konya in Anatolia, a man gave four persons a silver coin. The first one who was a Persian said, &quot;I will give this for buying some ''angur''&quot;. 

The second one who was an Arab said, &quot;No! I want ''inab'', not ''angur'', you deceitful!&quot; 

The third one who was a Turk said, &quot;No! I don't want ''inab''. I want ''üzüm''!&quot; 

The fourth one who was a Greek said, &quot;Quit all this talk! I want ''staphyle''!&quot;.

Soon a fighting erupted among the four men. They were striking at each other with their fists, while being ignorant of the hidden meaning of the names.

Then a master, with knowledge of numerous languages, arrived and gave them a cluster of grape. &quot;By means of this one silver coin, I granted the wishes of all of you. Your one coin became like four coins. Four enemies became as one from unity&quot;. 

The opposition among people takes place because of names. Peace occurs when they look at the underlying meaning. 

==Sources==
*Rumi, ''Masnavi-e Ma'navi'', translated by R. Nicholson

{{BookCat}}</text>
      <sha1>l65slvivgr8eis8bnwh4hzc3lb6ky0n</sha1>
    </revision>
  </page>
  <page>
    <title>OpenSCAD Tutorial</title>
    <ns>0</ns>
    <id>409751</id>
    <revision>
      <id>4669779</id>
      <parentid>4653365</parentid>
      <timestamp>2026-09-12T20:08:22Z</timestamp>
      <contributor>
        <username>~2026-49433-16</username>
        <id>3625807</id>
      </contributor>
      <comment>/* */</comment>
      <origin>4669779</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="7329" sha1="2ha3eh248hnkfqsesh7p3n0rf961ye0" xml:space="preserve">// --- 3D Printable Enclosure (ESP32 AI Chatbot Style) ---
// सभी माप मिलीमीटर (mm) में हैं।

// 1. Box Dimensions (बॉक्स का साइज़)
box_w = 45;      // बॉक्स की चौड़ाई
box_h = 45;      // बॉक्स की ऊंचाई
box_d = 35;      // बॉक्स की गहराई (मोटाई)
wall = 2;        // दीवारों की मोटाई (3D प्रिंटिंग के लिए 2mm सबसे अच्छा है)

// 2. Display Cutout (1.2 इंच डिस्प्ले के लिए)
// 1.2 इंच डिस्प्ले का दिखने वाला हिस्सा लगभग 26x26 mm होता है (आप इसे अपने हिसाब से बदल सकते हैं)
screen_w = 26; 
screen_h = 26; 

// 3. Type-C Port Cutouts
usb_w = 10;      // टाइप-C की चौड़ाई
usb_h = 4.5;     // टाइप-C की ऊंचाई
usb_gap = 12;    // तीनों पोर्ट्स के बीच की दूरी

// --- Main Box Module ---
module main_box() {
    difference() {
        // Outer Body
        translate([0,0, box_d/2])
            cube([box_w, box_h, box_d], center=true);
            
        // Inner Hollow Space
        translate([0,0, box_d/2 + wall])
            cube([box_w - (wall*2), box_h - (wall*2), box_d], center=true);
            
        // Screen Cutout (Top Face)
        translate([0, 0, box_d])
            cube([screen_w, screen_h, wall*3], center=true);
            
        // 3x Type-C Cutouts (Bottom Edge)
        // Center Port
        translate([0, -box_h/2, 10])
            cube([usb_w, wall*4, usb_h], center=true);
        // Left Port
        translate([-usb_gap, -box_h/2, 10])
            cube([usb_w, wall*4, usb_h], center=true);
        // Right Port
        translate([usb_gap, -box_h/2, 10])
            cube([usb_w, wall*4, usb_h], center=true);
    }
}

// --- Back Lid (ढक्कन) Module ---
module lid() {
    // इसे बॉक्स के बगल में प्रिंट करने के लिए खिसकाया गया है
    translate([box_w + 10, 0, 0]) { 
        union() {
            // Outer flat plate
            translate([0,0, wall/2])
                cube([box_w, box_h, wall], center=true);
            
            // Inner lip (जो बॉक्स के अंदर फिट होगा)
            // 0.4mm का टॉलरेंस दिया गया है ताकि यह आसानी से फिट हो जाए
            translate([0,0, wall + wall/2])
                cube([box_w - (wall*2) - 0.4, box_h - (wall*2) - 0.4, wall], center=true);
        }
    }
}

// Render both parts
main_box();
lid();

==Table of Contents==
{{Book search}}
{{Print version}}
* [[OpenSCAD Tutorial/Introduction|Introduction]]
* [[OpenSCAD Tutorial/Chapter 1|Chapter 1]]
*# [[/Chapter_1#A_few_words_about_OpenSCAD | A few words about OpenSCAD]]
*# [[/Chapter_1#Getting_started_with_the_Tutorial | Getting started with the Tutorial]]
*# [[/Chapter_1#Basic_information_about_the_OpenSCAD_environment | Basic information about the OpenSCAD environment]]
*# [[/Chapter_1#Creating_your_first_object | Creating your first object]]
*# [[/Chapter_1#Creating_a_slightly_different_cube | Creating a slightly different cube]]
*# [[/Chapter_1#Adding_more_objects_and_translating_objects | Adding more objects and translating objects]]
*# [[/Chapter_1#The_cylinder_primitive_and_rotating_objects | The cylinder primitive and rotating objects]]
*# [[/Chapter_1#Completing_your_first_model | Completing your first model]]
*# [[/Chapter_1#Creating_a_second model | Creating a second model]]

* [[/Chapter 2/]]
*# [[/Chapter_2#Scaling_parts_or_the_whole_model | Scaling parts or the whole model]]
*# [[/Chapter_2#Quick_quiz | Quick quiz]]
*# [[/Chapter_2#Parameterizing_parts_of_your_model | Parameterizing parts of your model]]
*# [[/Chapter_2#Parameterizing_more_parts_of_your_model | Parameterizing more parts of your model]]
*# [[/Chapter_2#Challenge | Challenge]]
*# [[/Chapter_2#Parameterizing_your_own_models | Parameterizing your own models]]

* [[/Chapter 3/]]
*# [[/Chapter_3#The_sphere_primitive_and_resizing_objects | The sphere primitive and resizing objects]]
*# [[/Chapter_3#Combining_objects_in_other_ways | Combining objects in other ways]]

* [[/Chapter 4/]]
*# [[/Chapter_4#Defining_and_using_modules | Defining and using modules]]
*# [[/Chapter_4#Parameterizing_modules | Parameterizing modules]]
*# [[/Chapter_4#Defining_default_values_of_module’s_parameters | Defining default values of module’s parameters]]
*# [[/Chapter_4#Separating_the_whole_model_into_modules | Separating the whole model into modules]]

* [[/Chapter 5/]]
*# [[/Chapter_5#Creating_and_utilizing_modules_as_separate_scripts | Creating and utilizing modules as separate scripts]]
*# [[/Chapter_5#Using_a_script_with_multiple_modules | Using a script with multiple modules]]
*# [[/Chapter_5#Using_the_MCAD_library | Using the MCAD library]]
*# [[/Chapter_5#Creating_even_more_parameterizable_modules | Creating even more parameterizable modules]]
*# [[/Chapter_5#Challenge | Challenge]]

* [[/Chapter 6/]]
*# [[/Chapter_6#OpenSCAD_variables | OpenSCAD variables]]
*# [[/Chapter_6#Conditional_variable_assignment | Conditional variable assignment]]
*# [[/Chapter_6#More_conditional_variable_assignments | More conditional variable assignments]]
*# [[/Chapter_6#Conditional_creation_of_objects_–_If_statement | Conditional creation of objects – If statement]]
*# [[/Chapter_6#Challenge | Challenge]]

* [[/Chapter 7/]]
*# [[/Chapter_7#Creating_repeating_patterns_of_parts/models_–_For_loops | Creating repeating patterns of parts/models – For loops]]
*# [[/Chapter_7#Creating_more_complex_patterns | Creating more complex patterns]]
*# [[/Chapter_7#Challenge | Challenge]]
*# [[/Chapter_7#Creating_patterns_of_patterns_–_Nested_for_loops | Creating patterns of patterns – Nested for loops]]

* [[/Chapter 8/]]
*# [[/Chapter_8#Rotationally_extruding_3D_objects_from_2D_objects | Rotationally extruding 3D objects from 2D objects]]
*# [[/Chapter_8#Challenge | Challenge]]
*# [[/Chapter_8#Linearly_extruding_3D_objects_from_2D_objects | Linearly extruding 3D objects from 2D objects]]

* [[/Chapter 9/]]
*# [[/Chapter_9#Doing_math_calculations_in_OpenSCAD | Doing math calculations in OpenSCAD]]
*# [[/Chapter_9#Creating_any_2D_object_with_the_polygon_primitive | Creating any 2D object with the polygon primitive]]
*# [[/Chapter_9#Challenge | Challenge]]
*# [[/Chapter_9#Creating_more_complex_object_using_the_polygon_primitive_and_math | Creating more complex object using the polygon primitive and math]]
*# [[/Chapter_9#Another_challenge | Another challenge]]

==Useful links==

* [https://www.openscad.org/index.html OpenSCAD's website]
* [https://www.openscad.org/downloads.html Download OpenSCAD]
* [https://www.openscad.org/cheatsheet/index.html Syntax cheat sheet]
* [[OpenSCAD User Manual/The OpenSCAD Language|The OpenSCAD Language Manual]] for use later as a reference.

{{Shelves|3D graphics software|computer programming languages|computer aided design}}
{{Status|100%}}
__NOTOC__</text>
      <sha1>2ha3eh248hnkfqsesh7p3n0rf961ye0</sha1>
    </revision>
    <revision>
      <id>4669780</id>
      <parentid>4669779</parentid>
      <timestamp>2026-09-12T20:08:49Z</timestamp>
      <contributor>
        <username>Vlsr1</username>
        <id>3511879</id>
      </contributor>
      <minor />
      <comment>Undid edits by [[Special:Contribs/~2026-49433-16|~2026-49433-16]] ([[User talk:~2026-49433-16|talk]]) to last version by ~2026-38676-31</comment>
      <origin>4669780</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="8136" sha1="auw4zqumt68v04ram66j6c7xwaxda6h" xml:space="preserve">[[File:Racing car with spoiler.jpg|300px|center|Racing car model]]
{{Book title|{{BOOKNAME}}}}/* * Heavy-Duty L-Bracket

&lt;nowiki/&gt;* Matches the exact specifications from the CAD Assessment Workflow Script.

&lt;nowiki/&gt;* Units: Millimeters (mm)

&lt;nowiki/&gt;*/

$fn = 50; // Smoothness for high-quality curves/fillets

module l_bracket() {

    difference() {

        // --- PHASE 1, 2, 3 &amp; 5: MAIN BODY (ADDITIVE FEATURES) ---

        union() {

            
            // 1. Base Flange (100mm wide, 80mm deep, 10mm thick)

            // Includes Phase 5 Cosmetic Outer Fillets (10mm radius) at the front

            hull() {

                translate([-40, 60, 0]) cylinder(h=10, r=10); // Front-left corner

                translate([ 40, 60, 0]) cylinder(h=10, r=10); // Front-right corner

                translate([-50, -10, 0]) cube([100, 10, 10]); // Square back edge to merge cleanly

            }

            
            // 2. Vertical Flange (100mm tall, 100mm wide, 10mm thick)

            // Includes Phase 5 Cosmetic Outer Fillets (10mm radius) at the top

            hull() {

                // Top rounded corners (cylinder rotated to face Y-axis)

                translate([-40, 0, 90]) rotate([90, 0, 0]) cylinder(h=10, r=10); 

                translate([ 40, 0, 90]) rotate([90, 0, 0]) cylinder(h=10, r=10); 

                translate([-50, -10, 0]) cube([100, 10, 10]); // Base connection

            }

            
            // 3. Central Support Gusset / Rib

            // 8mm thick, endpoints 15mm away from the inner corner

            hull() {

                translate([-4, 0, 10]) cube([8, 15, 0.1]); // Base footprint (15mm along Y)

                translate([-4, 0, 10]) cube([8, 0.1, 15]); // Vertical footprint (15mm along Z)

            }

            
            // 4. Phase 5: Structural Fillet (3mm radius at the inner corner)

            // Created by subtracting a cylinder from a small block along the corner

            translate([-50, 0, 10]) 

            difference() {

                cube([100, 3, 3]);

                // Cylinder shifted up and right to scoop out the curve

                translate([-1, 3, 3]) rotate([0, 90, 0]) cylinder(h=102, r=3, $fn=30);

            }

        }

        
        // --- PHASE 4: MOUNTING HOLES (SUBTRACTIVE FEATURES) ---

        
        // 5. Base Mounting Holes (Standard M8 Counterbore)

        // Positioned symmetrically, 20mm from edges (X=±30, Y=50)

        translate([-30, 50, 0]) {

            translate([0, 0, -1]) cylinder(h=12, r=4.5, $fn=30); // 9mm through hole

            translate([0, 0, 2]) cylinder(h=9, r=7.5, $fn=30);   // 15mm counterbore, 8mm deep

        }

        translate([ 30, 50, 0]) {

            translate([0, 0, -1]) cylinder(h=12, r=4.5, $fn=30);

            translate([0, 0, 2]) cylinder(h=9, r=7.5, $fn=30);

        }

        
        // 6. Vertical Face Mounting Holes (Standard M8 Clearance)

        // Positioned symmetrically, 20mm from top/side edges (X=±30, Z=80)

        // Rotate 90 degrees around X to push the cylinder through the Y axis

        translate([-30, 1, 80]) rotate([90, 0, 0]) cylinder(h=12, r=4.5, $fn=30);

        translate([ 30, 1, 80]) rotate([90, 0, 0]) cylinder(h=12, r=4.5, $fn=30);

    }

}

// Render the final model

color(&quot;Silver&quot;) l_bracket();

==Table of Contents==
{{Book search}}
{{Print version}}
* [[OpenSCAD Tutorial/Introduction|Introduction]]
* [[OpenSCAD Tutorial/Chapter 1|Chapter 1]]
*# [[/Chapter_1#A_few_words_about_OpenSCAD | A few words about OpenSCAD]]
*# [[/Chapter_1#Getting_started_with_the_Tutorial | Getting started with the Tutorial]]
*# [[/Chapter_1#Basic_information_about_the_OpenSCAD_environment | Basic information about the OpenSCAD environment]]
*# [[/Chapter_1#Creating_your_first_object | Creating your first object]]
*# [[/Chapter_1#Creating_a_slightly_different_cube | Creating a slightly different cube]]
*# [[/Chapter_1#Adding_more_objects_and_translating_objects | Adding more objects and translating objects]]
*# [[/Chapter_1#The_cylinder_primitive_and_rotating_objects | The cylinder primitive and rotating objects]]
*# [[/Chapter_1#Completing_your_first_model | Completing your first model]]
*# [[/Chapter_1#Creating_a_second model | Creating a second model]]

* [[/Chapter 2/]]
*# [[/Chapter_2#Scaling_parts_or_the_whole_model | Scaling parts or the whole model]]
*# [[/Chapter_2#Quick_quiz | Quick quiz]]
*# [[/Chapter_2#Parameterizing_parts_of_your_model | Parameterizing parts of your model]]
*# [[/Chapter_2#Parameterizing_more_parts_of_your_model | Parameterizing more parts of your model]]
*# [[/Chapter_2#Challenge | Challenge]]
*# [[/Chapter_2#Parameterizing_your_own_models | Parameterizing your own models]]

* [[/Chapter 3/]]
*# [[/Chapter_3#The_sphere_primitive_and_resizing_objects | The sphere primitive and resizing objects]]
*# [[/Chapter_3#Combining_objects_in_other_ways | Combining objects in other ways]]

* [[/Chapter 4/]]
*# [[/Chapter_4#Defining_and_using_modules | Defining and using modules]]
*# [[/Chapter_4#Parameterizing_modules | Parameterizing modules]]
*# [[/Chapter_4#Defining_default_values_of_module’s_parameters | Defining default values of module’s parameters]]
*# [[/Chapter_4#Separating_the_whole_model_into_modules | Separating the whole model into modules]]

* [[/Chapter 5/]]
*# [[/Chapter_5#Creating_and_utilizing_modules_as_separate_scripts | Creating and utilizing modules as separate scripts]]
*# [[/Chapter_5#Using_a_script_with_multiple_modules | Using a script with multiple modules]]
*# [[/Chapter_5#Using_the_MCAD_library | Using the MCAD library]]
*# [[/Chapter_5#Creating_even_more_parameterizable_modules | Creating even more parameterizable modules]]
*# [[/Chapter_5#Challenge | Challenge]]

* [[/Chapter 6/]]
*# [[/Chapter_6#OpenSCAD_variables | OpenSCAD variables]]
*# [[/Chapter_6#Conditional_variable_assignment | Conditional variable assignment]]
*# [[/Chapter_6#More_conditional_variable_assignments | More conditional variable assignments]]
*# [[/Chapter_6#Conditional_creation_of_objects_–_If_statement | Conditional creation of objects – If statement]]
*# [[/Chapter_6#Challenge | Challenge]]

* [[/Chapter 7/]]
*# [[/Chapter_7#Creating_repeating_patterns_of_parts/models_–_For_loops | Creating repeating patterns of parts/models – For loops]]
*# [[/Chapter_7#Creating_more_complex_patterns | Creating more complex patterns]]
*# [[/Chapter_7#Challenge | Challenge]]
*# [[/Chapter_7#Creating_patterns_of_patterns_–_Nested_for_loops | Creating patterns of patterns – Nested for loops]]

* [[/Chapter 8/]]
*# [[/Chapter_8#Rotationally_extruding_3D_objects_from_2D_objects | Rotationally extruding 3D objects from 2D objects]]
*# [[/Chapter_8#Challenge | Challenge]]
*# [[/Chapter_8#Linearly_extruding_3D_objects_from_2D_objects | Linearly extruding 3D objects from 2D objects]]

* [[/Chapter 9/]]
*# [[/Chapter_9#Doing_math_calculations_in_OpenSCAD | Doing math calculations in OpenSCAD]]
*# [[/Chapter_9#Creating_any_2D_object_with_the_polygon_primitive | Creating any 2D object with the polygon primitive]]
*# [[/Chapter_9#Challenge | Challenge]]
*# [[/Chapter_9#Creating_more_complex_object_using_the_polygon_primitive_and_math | Creating more complex object using the polygon primitive and math]]
*# [[/Chapter_9#Another_challenge | Another challenge]]

==Useful links==

* [https://www.openscad.org/index.html OpenSCAD's website]
* [https://www.openscad.org/downloads.html Download OpenSCAD]
* [https://www.openscad.org/cheatsheet/index.html Syntax cheat sheet]
* [[OpenSCAD User Manual/The OpenSCAD Language|The OpenSCAD Language Manual]] for use later as a reference.

{{Shelves|3D graphics software|computer programming languages|computer aided design}}
{{Status|100%}}
__NOTOC__</text>
      <sha1>auw4zqumt68v04ram66j6c7xwaxda6h</sha1>
    </revision>
  </page>
  <page>
    <title>EverQuest/Expansions</title>
    <ns>0</ns>
    <id>427953</id>
    <revision>
      <id>4669801</id>
      <parentid>3862309</parentid>
      <timestamp>2026-09-13T03:20:55Z</timestamp>
      <contributor>
        <username>Minorax</username>
        <id>3226541</id>
      </contributor>
      <origin>4669801</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1071" sha1="440yignae665un36mn2g2xyfyxrh4pc" xml:space="preserve">{{EverQuest/Header}}

There have been several expansions to the original game since release. Expansions are purchased separately and add significant content to the game (for example, new races, classes, continents, quests, and equipment). Additionally, the game is updated regularly through downloadable patches. The EQ expansions to date:

1 [[/Kunark|The Ruins of Kunark]] &amp;mdash; ''March 2000''

2 [[/Velious|The Scars of Velious]] &amp;mdash; ''December 2000''

3 [[/Luclin|The Shadows of Luclin]] &amp;mdash; ''December 2001''

4 [[/PoP|The Planes of Power]] &amp;mdash; ''October 2002''

5 [[/Ykesha|The Legacy of Ykesha]] &amp;mdash; ''March 2003''

6 [[/LDoN|Lost Dungeons of Norrath]] &amp;mdash; ''September 2003'' [[Image:50%.svg]]

7 [[/GoD|Gates of Discord]] &amp;mdash; ''February 2004'' [[Image:50%.svg]]

8 [[/OoW|Omens of War]] &amp;mdash; ''September 2004''

9 [[/DoN|Dragons of Norrath]] &amp;mdash; ''February 2005'' [[Image:25%.svg]]

10 [[/DoD|Depths of Darkhollow]] &amp;mdash; ''September 13, 2005'' [[Image:25%.svg]]

11 [[/PoR|Prohecy of Ro]] &amp;mdash; ''February 2006''

{{BookCat}}</text>
      <sha1>440yignae665un36mn2g2xyfyxrh4pc</sha1>
    </revision>
  </page>
  <page>
    <title>Grand Theft Auto: San Andreas/Appendices/PC Cheats</title>
    <ns>0</ns>
    <id>428069</id>
    <revision>
      <id>4669887</id>
      <parentid>3929115</parentid>
      <timestamp>2026-09-13T11:48:40Z</timestamp>
      <contributor>
        <username>Firzafp</username>
        <id>1253274</id>
      </contributor>
      <comment>GTA:SA DE cheats+</comment>
      <origin>4669887</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="6829" sha1="mk7xwizhon9z5cgq2ebt2436ox8g42q" xml:space="preserve">{{Grand Theft Auto: San Andreas/Header|title=Cheats for PC}}

EdisonCarter once again used his cheat-finding methods to crawl his way through the game finding cheats by choosing the closest path as well as textdumping from possible cheat keywords.

These cheats were taken from [http://www.gtasanandreas.net/news/single.php?id=1424 GTASanAndreas.net's news report], [http://www.maxbot.com/gta/sapc.htm EdisonCarter's updated cheat list], the [http://www.gtaforums.com/index.php?showtopic=194192 forum thread] where on-the-spot discoveries are made and findings announced.

These are both intelligible-word and button-press cheats. As more are discovered they will be added here and their unintelligible button-combo equivalent will be removed from the list below. All these cheats will still work in the meantime.

Cheats in italics have no word-based equivalent (so far) and have not been tested.

==Weapons, Health, Armor and Money==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;
| ''LXGIWYL'' || ''Weapon Set 1, Thug's Tools''
|-
|PROFESSIONALSKIT || Weapon Set 2, Professional Tools
|-
| ''UZUMYMW'' || ''Weapon Set 3, Nutter Tools''
|-
| ROCKETMAN || Have Jetpack
|-
| BRAKESPRACTISINGCEREMONY || Have Parachute
|-
| ''AFPHULTL'' || ''Have Katana (Ninja Sword)''
|-
| ''HESOYAM'' || ''Health, Armor, $250,000''
|-
| NOCHEAPSKATEBUREAU || Infinite Health
|-
| ''BAGUVIX'' || ''Infinite Health''
|-
| FULLCLIP || Infinite Ammo, No Reload
|-
| ''CVWKXAM'' || ''Infinite Oxygen (lung capacity when underwater''
|-
| GOODBYECRUELWORLD || Suicide
|-
| ANOSEONGLASS || Adrenaline Mode
|-
| ''AEDUWNV'' || ''Never Get Hungry''
|-
| PROFESSIONALKILLER || Hitman In All Weapon Stats
|}

==Police, Stats &amp; Gangs==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;
| PAWNDARBY || Never Wanted
|-
| BRINGITON || Six-Star Wanted Level
|-
| TURNDOWNTHEHEAT || lower Wanted Level Two Stars
|-
| TURNUPTHEHEAT || Increase Wanted Level Two Stars
|-
| TESTEDUCATIONALSKILLS || Clear Wanted Level
|-
| ''AEZAKMI'' || ''Never Wanted''
|-
| ''SJMAHPE'' || ''Recruit Anyone (9mm)''
|-
| ROCKETMAYHEM || Recruit Anyone (Rockets)
|-
| NATURALTALENT || Max All Vehicle Skill Stats
|-
| WORSHIPME || Max Respect
|-
| HELLOLADIES || Max Sex Appeal
|-
| UNDISTURBABLEBELLOWS || Really Fat CJ
|-
| ''KVGYZQK'' || ''Really Skinny CJ'' (0 fat and muscle)
|-
| BUFFMEUP || Max Muscle
|-
| BIFBUZZ || Gangs Control the Streets
|-
| ONLYHOMIESALLOWED || Gang Members Everywhere
|}

==Vehicle Spawning==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;
| OHDUDE || Spawn Hunter
|-
| ''AMOMHRER'' || ''Spawn Tanker Truck''
|-
| ITSALLBULL || Spawn Dozer
|-
| MONSTERMASH || Spawn Monster
|-
| FOURWHEELFUN || Spawn Quad
|-
| FLYINGTOSTUNT || Spawn Stunt Plane
|-
| ''AIWPRTON'' || ''Spawn Rhino Tank''
|-
| DOUGHNUTHANDLEDHANDICAP || Spawn Rancher
|-
| VROCKPOKEY || Spawn Hotring Racer 1
|-
| ''VPJTQWV'' || ''Spawn Hotring Racer 2''
|-
| OLDSPEEDDEMON || Spawn Bloodring Banger
|-
| WHERESTHEFUNERAL || Spawn Romero's Hearse
|-
| ''RZHSUEW'' || ''Spawn Caddy''
|-
| JUMPJET || Spawn Hydra
|-
| CELEBRITYSTATUS || Spawn Stretch
|-
| TRUEGRIME || Spawn Trashmaster
|-
| BACKROOMRESISTANCE || Spawn Vortex Hovercraft
|}

==Vehicles==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;
| SPEEDFREAK || All Cars Have Nitro
|-
| TAXINITRO || All taxis have nitro and hydraulic ('''''The Definitive Edition''' version only'')
|-
| DRIVEONWATER || Cars drive on water ('''''The Definitive Edition''' version only'')
|-
| BUBBLECARS || Cars Float Away When Hit
|-
| CHITTYCHITTYBANGBANG || Cars Fly
|-
| FLYINGFISH || Boats fly
|-
| ''FVTMNBZ'' || ''Traffic is Country Vehicles''
|-
| ''BMTPWHR'' || ''Country Vehicles and Peds, Get Born 2 Truck Outfit''
|-
| EVERYONEISPOOR || Traffic is Cheap Cars
|-
| EVERYONEISRICH || Traffic is Fast Cars
|-
| STICKLIKEGLUE || Perfect Handling
|-
| ''ZEIIVG'' || ''All green lights''
|-
| ''LLQPFBN'' || ''Pink traffic''
|-
| ''IOWDLAC'' || ''Black traffic''
|-
| GHOSTTOWN || Reduced Traffic
|-
| ''YLTEICZ'' || ''Aggressive Drivers''
|-
| WHEELSONLYPLEASE || Invisible car body (wheels visible)
|-
| ''CPKTNWT'' || ''Blow Up All Cars''
|-
| ''JCNRUAD'' || ''Smash n' Boom (player's vehicle acts like a Rhino tank)''
|-
| ''OUIQDMW'' || ''Full Weapon Aiming While Driving, never fall off bike''
|-
| ''VKYPQCF'' || ''Taxis Have Nitrous, L3 Bunny Hop''
|}

==Gameplay==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;
| BLUESUEDESHOES || Elvis Is Everywhere
|-
| NINJATOWN || Ninja Theme
|-
| LIFESABEACH || Beach Party Theme
|-
| CRAZYTOWN || Funhouse Theme
|-
| STINGLIKEABEE || Mega Punch [http://www.gtaforums.com/index.php?showtopic=194192&amp;view=findpost&amp;p=3357380]
|-
| KANGAROO || Mega Jump
|-
| EXPANDDOME || Big heads ('''''The Definitive Edition''' version only'')
|-
| CJPHONEHOME || Huge Bunny Hop
|-
| DOTHEPIMPCHEAT || Prostitutes pay Carl instead of taking Carl's money ('''''The Definitive Edition''' version only'')
|-
| ''BEKKNQV'' || ''Slut Magnet''
|-
| colspan=&quot;2&quot;| '''WARNING''': do not save with the following codes enabled, they cannot be turned off
|-
| ''FOOOXFT'' || ''Everyone is armed''
|-
| ''AJLOJYQY'' || ''Peds Attack Each Other, Get Golf Club''
|-
| ''BAGOWPG'' || ''Have a bounty on your head (Peds attack)''
|-
| ''BGLUAWML'' || ''Peds Attack You With Weapons, Rocket Launcher''
|-
| STATEOFEMERGENCY || Riot Mode
|}

==Weather and Time==
{| class=&quot;wikitable&quot; border=&quot;1&quot; cellpadding=&quot;4&quot; cellspacing=&quot;0&quot; style=&quot;margin: 0 0 1em 1em; border: 1px grey solid; border-collapse: collapse; font-size: 95%;&quot;

| SPEEDITUP || Faster Gameplay
|-
| SLOWITDOWN || Slower Gameplay
|-
| ''YSOHNUL'' || ''Faster Clock''
|-
| PLEASANTLYWARM || Sunny Weather
|-
| TOODAMNHOT || Very Sunny Weather
|-
| ''ALNSFMZO'' || ''Overcast Weather''
|-
| ''AUIFRVQS'' || ''Rainy Weather''
|-
| ''CFVFGMJ'' || ''Foggy Weather''
|-
| SCOTTISHSUMMER || Thunderstorm
|-
| HITHERSALVATORERIDES || Sandstorm
|-
| DEBUGCAMPPEACE || Orange Sky, Clock Fixed at 21:00 (like in the beta screenshots)
|-
| NIGHTPROWLER || Always Midnight
|}

According to EdisonCarter's findings, the following cheats were not implemented in the PC version, however has been implemented to &quot;The Definitive Edition&quot; version (see above):
* Drive On Water
* Do Nothing
* Hookers Pay You


{{BookCat}}</text>
      <sha1>mk7xwizhon9z5cgq2ebt2436ox8g42q</sha1>
    </revision>
  </page>
  <page>
    <title>Grand Theft Auto: San Andreas/Missions/Trucking</title>
    <ns>0</ns>
    <id>428212</id>
    <revision>
      <id>4669782</id>
      <parentid>3863551</parentid>
      <timestamp>2026-09-12T20:19:42Z</timestamp>
      <contributor>
        <username>WereSpielChequers</username>
        <id>248949</id>
      </contributor>
      <comment>/* Mission 6 */ c/e</comment>
      <origin>4669782</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="2318" sha1="hwf67vpb6b483djsp4owatj7d9wcsi3" xml:space="preserve">These missions become available after you complete the mission with Catalina where you steal a gas truck.

==Trucking==

'''Vehicle:''' Linerunner, Tanker, and Roadtrain with various trailers attached. Stop by Whittaker's depot after completing Catalina's &quot;Tanker Commander&quot; mission and step into the mission circle to activate the mission.

'''Tips:''' Use the first-person view for more accurate driving. Take turns and steep hills carefully to avoid disconnecting the trailer. Avoid other traffic on the road. On damage-based missions, drive carefully overall; on speed-based missions, you can afford to be careless with damage, but avoid hitting obstacles than can stop your movement.

'''Rewards:''' Whittaker's &quot;RS Haul&quot; becomes an asset that generates money automatically.

==Mission 1==
'''Tanker to Red County:''' Deliver a Tanker to Red County, Simple run with a timelimit.
'''Reward:''' $1,000.

==Mission 2==
'''Tanker to Montgomery:''' Deliver a Tanker to Montgomery, Harder run with no timelimit but damage limit and fragile load.
'''Reward:''' $1,500 - Damage.

==Mission 3==
'''Illegal Goods to Ocean Docks, Los Santos:''' Deliver a container of Illegal Goods to Ocean Docks, Los Santons. The truck attracts police attention (3 Stars). No Time Limit. Warning this is a high load so some of the tunnels will cause the trailer to come off the truck. If this happens you have 45 seconds to reattached. Expect lots of police, the police helicopter and media vans to be all over you.
'''Reward:''' $2,000.

==Mission 4==
'''Goods to Whetstone, South San Andreas:''' Deliver goods to Whestone, South San Andres. Has to be done quickly. Timelimit.
'''Reward:''' $3,000.

==Mission 5==
'''Extremely Fragile Goods to Easter Basin, San Fierro:''' Deliver fragile goods to Easter Basin, San Fiero.
'''Reward:''' $4,000 - Damage.

==Mission 6==
'''Illegal Goods to Easter Bay Airport:''' Deliver a container of Illegal Goods to Easter Bay Airport, San Fierro. The truck attracts police attention (3 Stars). No Time Limit. Warning this is a high load so some of the tunnels will cause the trailer to come off the truck. If this happens you have 45 seconds to reattach it. Expect lots of police, the police helicopter and media vans to be all over you.
'''Reward:''' $5,000.

==Mission 7==
==Mission 8==

{{BookCat}}</text>
      <sha1>hwf67vpb6b483djsp4owatj7d9wcsi3</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:Xandradi</title>
    <ns>3</ns>
    <id>464381</id>
    <revision>
      <id>4669791</id>
      <parentid>4624672</parentid>
      <timestamp>2026-09-13T02:21:29Z</timestamp>
      <contributor>
        <username>1234qwer1234qwer4</username>
        <id>1406991</id>
      </contributor>
      <comment>new topic ([[mw:c:Special:MyLanguage/User:JWBTH/CD|CD]])</comment>
      <origin>4669791</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1825" sha1="tcqc378d24g7q1u5jb21oprvcymxkuo" xml:space="preserve">(abandoned)

== Recent edits ==

{{tmbox|type=warning|text=[[Wikibooks:Welcome|Wikibooks]] invites everyone to contribute constructively to our collection. However, your [[Special:Contributions/Xandradi|recent edits]] may be considered [[Wikibooks:Vandalism|vandalism]] by your fellow contributors. Please improve our collection and stop damaging the hard work of others. If you continue in this manner '''you may be blocked from editing without further warning'''. Thanks. }} —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 13:21, 30 January 2024 (UTC) [[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 13:21, 30 January 2024 (UTC)

== Chess Opening Theory/Position ==

Hi, just a quick note about [[:Template:Chess Opening Theory/Position]]. 

It no longer requires fields like &lt;code&gt;|rd|nd|bd|...&lt;/code&gt; etc. to show the board position. The template now interprets the board position automatically based on the page name. These fields can be deleted. 

Best wishes [[User:JCrue|JCrue]] ([[User talk:JCrue|discuss]] • [[Special:Contributions/JCrue|contribs]]) 23:02, 20 March 2026 (UTC)

==[[:Chess Opening Theory/1. g4/1...Na6]]==
{{tmbox|type=delete|text='''Xandradi, please [[Wikibooks:Requests for deletion#Chess Opening Theory/1. g4/1...Na6|share your thoughts]] about whether to [[WB:WIW|keep]] or [[WB:DP|delete]] &quot;[[:Chess Opening Theory/1. g4/1...Na6|Chess Opening Theory/1. g4/1...Na6]]&quot;.'''&lt;br /&gt;You are being notified because you have contributed to this work. [[User:1234qwer1234qwer4|𝟙𝟤𝟯𝟺𝐪𝑤𝒆𝓇𝟷𝟮𝟥𝟜𝓺𝔴𝕖𝖗𝟰]] ([[User talk:1234qwer1234qwer4|𝗍𝗮𝘭𝙠]]) 02:21, 13 September 2026 (UTC)}}</text>
      <sha1>tcqc378d24g7q1u5jb21oprvcymxkuo</sha1>
    </revision>
  </page>
  <page>
    <title>Chess Opening Theory/1. g4/1...Na6</title>
    <ns>0</ns>
    <id>468985</id>
    <revision>
      <id>4669790</id>
      <parentid>4428941</parentid>
      <timestamp>2026-09-13T02:20:53Z</timestamp>
      <contributor>
        <username>1234qwer1234qwer4</username>
        <id>1406991</id>
      </contributor>
      <comment>{{rfd}}</comment>
      <origin>4669790</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="408" sha1="78l4vyvlaiw1o3mmrb5yvd32dhxkazm" xml:space="preserve">{{rfd}}
{{Chess Opening Theory/Position|Grob's Attack}}
{{Wikipedia|Grob's Attack}}
== 1...Na6?! ==
This move doesn't do anything to help Black's position, but rather hurts it. The knight on a6 is not doing anything important or attacking White's weak kingside. White can develop with [[/2. Nf3/]], [[/2. Bg2/]], or take the center with [[/2. d4/]], [[/2. e4/]].

{{ChessMid}}
{{Chess Opening Theory/Footer}}</text>
      <sha1>78l4vyvlaiw1o3mmrb5yvd32dhxkazm</sha1>
    </revision>
  </page>
  <page>
    <title>Aros/Developer/Docs/Libraries/Codesets</title>
    <ns>0</ns>
    <id>475469</id>
    <revision>
      <id>4669771</id>
      <parentid>4601619</parentid>
      <timestamp>2026-09-12T16:59:10Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669771</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="128904" sha1="ny08qwdys9kn4l5qr4d2v1p8gcqxb02" xml:space="preserve">{{ArosNav}}

==Introduction==

Character set (charsets) encoding is the process of assigning numbers to graphical characters, especially the written characters of human language

Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251      – Cyrillic (Amiga)
    ISO-8859-1      – Latin 1 aka Western European ASCII based 
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2      – Latin-2 aka Central/East European
    ISO-8859-3      – South European
    ISO-8859-4      – North European
    ISO-8859-5      – Slavic languages
    ISO-8859-9      – Turkish
    ISO-8859-15     – West European II
    ISO-8859-16     – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)

Windows-1252 was first character set in Windows. It was a copy of ASCII, but used 8-bits to represent 256 different characters (international letters). Windows-1252 is supported by all browsers.
&lt;/pre&gt;


==Source Code==

&lt;pre&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;exec/libraries.h&gt;
#include &lt;libraries/codesets.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;proto/exec.h&gt;

#include &lt;stdio.h&gt;

/* This is just a very quickly written test, not a full-featured convertor */
#define BUF_SIZE 102400

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace *ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

struct codeset *srcCodeset;
struct codeset *destCodeset;

int main(int argc, char **argv)
{
  char *buf, *destbuf;
  ULONG destlen;
  FILE *f;

  if (argc &lt; 4)
  {
    fprintf(stderr, &quot;Usage: %s &lt;source codeset&gt; &lt;destination codeset&gt; &lt;source file&gt;\n&quot;, argv[0]);
    return 0;
  }
  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
     GETINTERFACE(ICodesets, CodesetsBase))
  {
    srcCodeset = CodesetsFind(argv[1], CSA_FallbackToDefault, FALSE, TAG_DONE);
    if (srcCodeset)
    {
      destCodeset = CodesetsFind(argv[2], CSA_FallbackToDefault, FALSE, TAG_DONE);
      if (destCodeset)
      {
        buf = AllocMem(BUF_SIZE, MEMF_CLEAR);

        if (buf)
        {
          f = fopen(argv[3], &quot;r&quot;);
          if (f)
          {
            fread(buf, BUF_SIZE-1, 1, f);
            fclose(f);
            destbuf = CodesetsConvertStr(CSA_SourceCodeset, (IPTR)srcCodeset,
                                         CSA_DestCodeset, (IPTR)destCodeset,
                                         CSA_Source, (IPTR)buf,
                                         CSA_DestLenPtr, (IPTR)&amp;destlen,
                                         TAG_DONE);
            if (destbuf)
            {
              fprintf(stderr, &quot;Result length: %u\n&quot;, (unsigned int)destlen);
              fwrite(destbuf, destlen, 1, stdout);
              fputc('\n', stderr);
              CodesetsFreeA(destbuf, NULL);
            }
          else
            fprintf(stderr, &quot;Failed to convert text!\n&quot;);
          }
          FreeMem(buf, BUF_SIZE);
        }
        else
          fprintf(stderr, &quot;Failed to allocate %d bytes for buffer\n&quot;, BUF_SIZE);
      }
      else
        fprintf(stderr, &quot;Unknown destination codeset %s\n&quot;, argv[2]);
    }
    else
      fprintf(stderr, &quot;Unknown source codeset %s\n&quot;, argv[1]);

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
  }
  else
    fprintf(stderr, &quot;Failed to open codesets.library!\n&quot;);

  return 0;
}
&lt;/pre&gt;


&lt;pre&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;proto/exec.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define ISO8859_1_STR &quot;Schmöre bröd, schmöre bröd, bröd bröd bräd.&quot;
#define CP1251_STR    &quot;1251 êîäèðîâêà äëÿ ïðèìåðà.&quot;
#define ASCII_STR     &quot;latin 1 bla bla bla.&quot;
#define KOI8R_STR     &quot;koi îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace* ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

int main(void)
{
  int res;

  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
      GETINTERFACE(ICodesets, CodesetsBase))
  {
    IPTR errNum = 0;
    struct codeset *cs;

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ISO8859_1_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              TAG_DONE)))
    {
      printf(&quot;Identified ISO8859_1_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ISO8859_1_STR));
    }
    else
      printf(&quot;couldn't identify ISO8859_1_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)CP1251_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified CP1251_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(CP1251_STR));
    }
    else
      printf(&quot;couldn't identify CP1251_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ASCII_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified ASCII_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ASCII_STR));
    }
    else
      printf(&quot;couldn't identify ASCII_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)KOI8R_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified KOI8R_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(KOI8R_STR));
    }
    else
      printf(&quot;couldn't identify KOI8R_STR!\n&quot;);

    res = 0;

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
    CodesetsBase = NULL;
  }
  else
  {
    printf(&quot;can't open %s %d+\n&quot;,CODESETSNAME,CODESETSVER);
    res = 20;
  }

  return res;
}
&lt;/pre&gt;


From [https://github.com/sba1/simplemail SimpleMail] 

&lt;pre&gt;
/***************************************************************************
 SimpleMail - Copyright (C) 2000 Hynek Schlawack and Sebastian Bauer

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
***************************************************************************/

/**
 * @brief Support of codesets.
 *
 * @file codesets.c
 */

#include &quot;codesets.h&quot;

#include &lt;ctype.h&gt;
#include &lt;dirent.h&gt; /* dir stuff */
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;unistd.h&gt;

#include &quot;codesets_table.h&quot;
#include &quot;debug.h&quot;
#include &quot;punycode.h&quot;
#include &quot;smintl.h&quot;
#include &quot;support_indep.h&quot;

/* from ConvertUTF.h */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8.  Header file.

    Several funtions are included here, forming a complete set of
    conversions between the three formats.  UTF-7 is not included
    here, but is handled in a separate source file.

    Each of these routines takes pointers to input buffers and output
    buffers.  The input buffers are const.

    Each routine converts the text between *sourceStart and sourceEnd,
    putting the result into the buffer between *targetStart and
    targetEnd. Note: the end pointers are *after* the last item: e.g.
    *(sourceEnd - 1) is the last item.

    The return result indicates whether the conversion was successful,
    and if not, whether the problem was in the source or target buffers.
    (Only the first encountered problem is indicated.)

    After the conversion, *sourceStart and *targetStart are both
    updated to point to the end of last text successfully converted in
    the respective buffers.

    Input parameters:
	sourceStart - pointer to a pointer to the source buffer.
		The contents of this are modified on return so that
		it points at the next thing to be converted.
	targetStart - similarly, pointer to pointer to the target buffer.
	sourceEnd, targetEnd - respectively pointers to the ends of the
		two buffers, for overflow checking only.

    These conversion functions take a ConversionFlags argument. When this
    flag is set to strict, both irregular sequences and isolated surrogates
    will cause an error.  When the flag is set to lenient, both irregular
    sequences and isolated surrogates are converted.

    Whether the flag is strict or lenient, all illegal sequences will cause
    an error return. This includes sequences such as: &lt;F4 90 80 80&gt;, &lt;C0 80&gt;,
    or &lt;A0&gt; in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
    must check for illegal sequences.

    When the flag is set to lenient, characters over 0x10FFFF are converted
    to the replacement character; otherwise (when the flag is set to strict)
    they constitute an error.

    Output parameters:
	The value &quot;sourceIllegal&quot; is returned from some routines if the input
	sequence is malformed.  When &quot;sourceIllegal&quot; is returned, the source
	value will point to the illegal value that caused the problem. E.g.,
	in UTF-8 when a sequence is malformed, it points to the start of the
	malformed sequence.

    Author: Mark E. Davis, 1994.
    Rev History: Rick McGowan, fixes &amp; updates May 2001.

------------------------------------------------------------------------ */

/* ---------------------------------------------------------------------
    The following 4 definitions are compiler-specific.
    The C standard does not guarantee that wchar_t has at least
    16 bits, so wchar_t is no less portable than unsigned short!
    All should be unsigned values to avoid sign extension during
    bit mask &amp; shift operations.
------------------------------------------------------------------------ */

typedef unsigned long	UTF32;	/* at least 32 bits */
typedef unsigned short	UTF16;	/* at least 16 bits */
typedef unsigned char	UTF8;	/* typically 8 bits */
typedef unsigned char	Boolean; /* 0 or 1 */

/* Some fundamental constants */
#define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
#define UNI_MAX_BMP (UTF32)0x0000FFFF
#define UNI_MAX_UTF16 (UTF32)0x0010FFFF
#define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF

typedef enum {
	conversionOK, 		/* conversion successful */
	sourceExhausted,	/* partial character in source, but hit end */
	targetExhausted,	/* insuff. room in target for conversion */
	sourceIllegal,		/* source sequence is illegal/malformed */
  sourceCorrupt,    /* source contains invalid UTF-7 */ /* addded */
} ConversionResult;

typedef enum {
	strictConversion = 0,
	lenientConversion
} ConversionFlags;

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags);

static Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);

/* --------------------------------------------------------------------- */

int utf8islegal(const char *source, const char *sourceend)
{
	return isLegalUTF8Sequence((const UTF8*)source, (const UTF8*)sourceend);
}

/* --------------------------------------------------------------------- */

/* ConvertUTF.c */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8. Source code file.
	Author: Mark E. Davis, 1994.
	Rev History: Rick McGowan, fixes &amp; updates May 2001.

    See the header file &quot;ConvertUTF.h&quot; for complete documentation.

------------------------------------------------------------------------ */


/*#include &quot;ConvertUTF.h&quot;*/
/*#ifdef CVTUTF_DEBUG*/
#include &lt;stdio.h&gt;
/*#endif*/

static const int halfShift	= 10; /* used for shifting by 10 bits */

static const UTF32 halfBase	= 0x0010000UL;
static const UTF32 halfMask	= 0x3FFUL;

#define UNI_SUR_HIGH_START	(UTF32)0xD800
#define UNI_SUR_HIGH_END	(UTF32)0xDBFF
#define UNI_SUR_LOW_START	(UTF32)0xDC00
#define UNI_SUR_LOW_END		(UTF32)0xDFFF
#define false			0
#define true			1

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		ch = *source++;
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF32* target = *targetStart;
	UTF32 ch, ch2;
	while (source &lt; sourceEnd) {
		ch = *source++;
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			/* an unpaired low surrogate */
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		*target++ = ch;
	}
	*sourceStart = source;
	*targetStart = target;
#ifdef CVTUTF_DEBUG
if (result == sourceIllegal) {
    fprintf(stderr, &quot;ConvertUTF16toUTF32 illegal seq 0x%04x,%04x\n&quot;, ch, ch2);
    fflush(stderr);
}
#endif
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Index into the table below with the first byte of a UTF-8 sequence to
 * get the number of trailing bytes that are supposed to follow it.
 */

static const char trailingBytesForUTF8[256] = {
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
	2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, 3,3,3,3,3,3,3,3,4,4,4,4,5,5,5,5
};

/*
 * Magic values subtracted from a buffer value during UTF8 conversion.
 * This table contains as many values as there might be trailing bytes
 * in a UTF-8 sequence.
 */
static const UTF32 offsetsFromUTF8[6] = { 0x00000000UL, 0x00003080UL, 0x000E2080UL,
					 0x03C82080UL, 0xFA082080UL, 0x82082080UL };

/*
 * Once the bits are split out into bytes of UTF-8, this is a mask OR-ed
 * into the first byte, depending on how many bytes follow.  There are
 * as many entries in this table as there are UTF-8 sequence types.
 * (I.e., one byte sequence, two byte... six byte sequence.)
 */
static const UTF8 firstByteMark[7] = { 0x00, 0x00, 0xC0, 0xE0, 0xF0, 0xF8, 0xFC };

/* --------------------------------------------------------------------- */

/* The interface converts a whole buffer to avoid function-call overhead.
 * Constants have been gathered. Loops &amp; conditionals have been removed as
 * much as possible for efficiency, in favor of drop-through switches.
 * (See &quot;Note A&quot; at the bottom of the file for equivalent code.)
 * If your compiler supports it, the &quot;isLegalUTF8&quot; call can be turned
 * into an inline function.
 */

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* If we have a surrogate pair, convert to UTF32 first. */
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			UTF32 ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Utility routine to tell whether a sequence of bytes is legal UTF-8.
 * This must be called with the length pre-determined by the first byte.
 * If not calling this from ConvertUTF8to*, then the length can be set by:
 *	length = trailingBytesForUTF8[*source]+1;
 * and the sequence is illegal right away if there aren't that many bytes
 * available.
 * If presented with a length &gt; 4, this returns false.  The Unicode
 * definition of UTF-8 goes up to 4-byte sequences.
 */

static Boolean isLegalUTF8(const UTF8 *source, int length) {
	UTF8 a;
	const UTF8 *srcptr = source+length;
	switch (length) {
	default: return false;
		/* Everything else falls through when &quot;true&quot;... */
	case 4: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 3: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 2: if ((a = (*--srcptr)) &gt; 0xBF) return false;
		switch (*source) {
		    /* no fall-through in this inner switch */
		    case 0xE0: if (a &lt; 0xA0) return false; break;
		    case 0xF0: if (a &lt; 0x90) return false; break;
		    case 0xF4: if (a &gt; 0x8F) return false; break;
		    default:  if (a &lt; 0x80) return false;
		}
    	case 1: if (*source &gt;= 0x80 &amp;&amp; *source &lt; 0xC2) return false;
		if (*source &gt; 0xF4) return false;
	}
	return true;
}

/* --------------------------------------------------------------------- */

/*
 * Exported function to return whether a UTF-8 sequence is legal or not.
 * This is not used here; it's just exported.
 */
Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd) {
	int length = trailingBytesForUTF8[*source]+1;
	if (source+length &gt; sourceEnd) {
	    return false;
	}
	return isLegalUTF8(source, length);
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
				source -= extraBytesToRead; /* return to the start */
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* surrogates of any stripe are not legal UTF32 characters */
		if (flags == strictConversion ) {
			if ((ch &gt;= UNI_SUR_HIGH_START) &amp;&amp; (ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF32* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		} else {
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* ---------------------------------------------------------------------

	Note A.
	The fall-through switches in UTF-8 reading code save a
	temp variable, some decrements &amp; conditionals.  The switches
	are equivalent to the following loop:
		{
			int tmpBytesToRead = extraBytesToRead+1;
			do {
				ch += *source++;
				--tmpBytesToRead;
				if (tmpBytesToRead) ch &lt;&lt;= 6;
			} while (tmpBytesToRead &gt; 0);
		}
	In UTF-8 writing code, the switches on &quot;bytesToWrite&quot; are
	similarly unrolled loops.

   --------------------------------------------------------------------- */

/* Some code has been taken from the ConvertUTF7.c file (the utf7 stuff below),
   this is the copyright notice */

/* ================================================================ */
/*
File:   ConvertUTF7.c
Author: David B. Goldsmith
Copyright (C) 1994, 1996 IBM Corporation All rights reserved.
Revisions: Header update only July, 2001.

This code is copyrighted. Under the copyright laws, this code may not
be copied, in whole or part, without prior written consent of IBM Corporation.

IBM Corporation grants the right to use this code as long as this ENTIRE
copyright notice is reproduced in the code.  The code is provided
AS-IS, AND IBM CORPORATION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT
WILL IBM CORPORATION BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING,
WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY
LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THIS CODE, EVEN
IF IBM CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATION MAY NOT APPLY TO YOU.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the
government is subject to restrictions as set forth in subparagraph
(c)(l)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and FAR 52.227-19.

This code may be protected by one or more U.S. and International
Patents.

*/


/* ------------------------------------- */

struct list codesets_list;

/**************************************************************************
 Returns the supported codesets as an null terminated string array
**************************************************************************/
char **codesets_supported(void)
{
	static char **array;

	if (array) return array;

	if ((array = (char**)malloc(sizeof(char*)*(list_length(&amp;codesets_list)+1))))
	{
		struct codeset *code;
		int i;

		SM_DEBUGF(15,(&quot;%ld supported Codesets:\n&quot;,list_length(&amp;codesets_list)));

		code = (struct codeset*)list_first(&amp;codesets_list);
		i = 0;

		while (code)
		{
			SM_DEBUGF(15,(&quot;  %p next=%p prev=%p list=%p name=%p %s alt=%p char=%p\n&quot;,code,code-&gt;node.next,code-&gt;node.prev,code-&gt;node.list,code-&gt;name,code-&gt;name,code-&gt;alt_name,code-&gt;characterization));
			array[i++] = code-&gt;name;
			code = (struct codeset*)node_next(&amp;code-&gt;node);
		}
		array[i] = NULL;
	}
	return array;
}

/**************************************************************************
 The compare function
**************************************************************************/
static int codesets_cmp_unicode(const void *arg1, const void *arg2)
{
	char *a1 = (char*)((struct single_convert*)arg1)-&gt;utf8 + 1;
	char *a2 = (char*)((struct single_convert*)arg2)-&gt;utf8 + 1;
	return (int)strcmp(a1,a2);
}

/**
 * Reads the codeset table from the given filename and adds it.
 *
 * @param name
 * @return
 */
static int codesets_read_table(char *name)
{
	char buf[512];

	FILE *fh = fopen(name,&quot;r&quot;);

	if (fh)
	{
		struct codeset *codeset;
		if ((codeset = (struct codeset*)malloc(sizeof(struct codeset))))
		{
			int i;
			memset(codeset,0,sizeof(struct codeset));

			for (i=0;i&lt;256;i++)
				codeset-&gt;table[i].code = codeset-&gt;table[i].ucs4 = i;

			while (myreadline(fh,buf))
			{
				char *result;
				if ((result = get_key_value(buf,&quot;Standard&quot;))) codeset-&gt;name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;AltStandard&quot;))) codeset-&gt;alt_name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;ReadOnly&quot;))) codeset-&gt;read_only = !!atoi(result);
				else if ((result = get_key_value(buf,&quot;Characterization&quot;)))
				{
					if ((result[0] == '_') &amp;&amp; (result[1] == '(') &amp;&amp; (result[2] == '&quot;'))
					{
						char *end = strchr(result+3,'&quot;');
						if (end)
						{
							char *txt = mystrndup(result+3,end-(result+3));
							if (txt) codeset-&gt;characterization = mystrdup(_(txt));
							free(txt);
						}
					}
				} else
				{
					char *p = buf;
					int fmt2 = 0;

					if ((*p == '=') || (fmt2 = ((*p == '0') || (*(p+1)=='x'))))
					{
						p++;
						p += fmt2;

						i = strtol(p,&amp;p,16);
						if (i &gt; 0 &amp;&amp; i &lt; 256)
						{
							while (isspace((unsigned char)*p)) p++;

							if (!mystrnicmp(p,&quot;U+&quot;,2))
							{
								p += 2;
								codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,16);
							} else
							{
								if (*p!='#') codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,0);
							}
						}
					}
				}
			}

			for (i=0;i&lt;256;i++)
			{
				UTF32 src = codeset-&gt;table[i].ucs4;
				UTF32 *src_ptr = &amp;src;
				UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];
				ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
				*dest_ptr = 0;
				codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
			}

			memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
			qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
			list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);
		}
		fclose(fh);
	}
	return 1;
}

/*****************************************************************************/

int codesets_init(void)
{
	int i;
	struct codeset *codeset;
	UTF32 src;

	SM_ENTER;

	list_init(&amp;codesets_list);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 0;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1 + Euro&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European (with EURO)&quot;));
	codeset-&gt;read_only = 1;

	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i==164) src = 0x20AC; /* the EURO sign */
		else src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-2&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Central/East European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_2_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-3&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_3_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-4&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;North European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_4_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;KOI8-R&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Russian&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0x80) src = i;
		else src = koi8r_to_ucs4[i-0x80];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-5&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Slavic languages&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_5_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-9&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Turkish&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_9_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-15&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European II&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_15_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-16&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South-Eastern European&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_16_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amigapl_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amiga1251_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	SM_DEBUGF(15,(&quot;%ld internal charsets\n&quot;,list_length(&amp;codesets_list)));

	{
		/* dynamicaly loaded */

		DIR *dfd; /* directory descriptor */
		struct dirent *dptr; /* dir entry */
		char path[380];

		getcwd(path, sizeof(path));
		if (chdir(SM_CHARSET_DIR) != -1)
		{
			if ((dfd = opendir(SM_CURRENT_DIR)))
			{
				while ((dptr = readdir(dfd)) != NULL)
				{
					if (!strcmp(&quot;.&quot;,dptr-&gt;d_name) || !strcmp(&quot;..&quot;,dptr-&gt;d_name)) continue;
					SM_DEBUGF(15,(&quot;Loading \&quot;%s\&quot; charset\n&quot;,dptr-&gt;d_name,list_length(&amp;codesets_list)));
					codesets_read_table(dptr-&gt;d_name);
				}
				closedir(dfd);
			}
			chdir(path);
		}
	}

	SM_RETURN(1,&quot;%ld&quot;);
}

/*****************************************************************************/

void codesets_cleanup(void)
{
	struct codeset *codeset;

	while ((codeset = (struct codeset*)list_remove_tail(&amp;codesets_list)))
	{
		free(codeset-&gt;name);
		free(codeset-&gt;alt_name);
		free(codeset-&gt;characterization);
		free(codeset);
	}
}

/*****************************************************************************/

struct codeset *codesets_find(const char *name)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);

	/* Return ISO-8859-1 as default codeset */
	if (!name) return codeset;

	while (codeset)
	{
		if (!mystricmp(name,codeset-&gt;name) || !mystricmp(name,codeset-&gt;alt_name)) return codeset;
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}
	return NULL;
}

/*****************************************************************************/

int codesets_unconvertable_chars(struct codeset *codeset, const char *text, int text_len)
{
	struct single_convert conv;
	const char *text_ptr = text;
	int i;
	int errors = 0;

	for (i=0;i &lt; text_len;i++)
	{
		unsigned char c = *text_ptr++;
		if (c)
		{
			int len = trailingBytesForUTF8[c];
			conv.utf8[1] = c;
			strncpy((char*)&amp;conv.utf8[2],text_ptr,len);
			conv.utf8[2+len] = 0;
			text_ptr += len;

			if (!bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode))
				errors++;
		} else break;
	}

	return errors;
}

/*****************************************************************************/

struct codeset *codesets_find_best(const char *text, int text_len, int *error_ptr)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);
	struct codeset *best_codeset = NULL;
	int best_errors = text_len;

	while (codeset)
	{
		if (!codeset-&gt;read_only)
		{
			int errors = codesets_unconvertable_chars(codeset, text, text_len);

			if (errors &lt; best_errors)
			{
				best_codeset = codeset;
				best_errors = errors;
			}
			if (!best_errors) break;
		}
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}

	if (!best_codeset) best_codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (error_ptr) *error_ptr = best_errors;

	return best_codeset;
}

/*****************************************************************************/

int utf8len(const utf8 *str)
{
	int len ;
	unsigned char c;

	if (!str) return 0;
	len = 0;

	while ((c = *str++))
	{
		len++;
		str += trailingBytesForUTF8[c];
	}

	return len;
}

/*****************************************************************************/

utf8 *utf8dup(const utf8 *str)
{
	return (utf8*)mystrdup((char*)str);
}

/*****************************************************************************/

int utf8realpos(const utf8 *str, int pos)
{
	const utf8 *str_save = str;
	unsigned char c;

	if (!str) return 0;

	while (pos &amp;&amp; (c = *str))
	{
		pos--;
		str += trailingBytesForUTF8[c] + 1;
	}
	return str - str_save;
}

/*****************************************************************************/

int utf8charpos(const utf8 *str, int pos)
{
	int cp = 0;
	unsigned char c;

	while (pos &gt; 0 &amp;&amp; (c = *str))
	{
		str += trailingBytesForUTF8[c] + 1;
		pos -= trailingBytesForUTF8[c] + 1;
		cp++;
	}
	return cp;
}

/*****************************************************************************/

int utf8bytes(const utf8 *str)
{
	unsigned char c = *str;
	return trailingBytesForUTF8[c] + 1;
}

/*****************************************************************************/

utf8 *utf8ncpy(utf8 *to, const utf8 *from, int n)
{
	utf8 *saved_to = to;
	for (;n;n--)
	{
		unsigned char c = *from++;
		int len = trailingBytesForUTF8[c];

		*to++ = c;
		for (;len;len--)
		{
			*to++ = *from++;
		}
	}
	return saved_to;
}

/*****************************************************************************/

utf8 *utf8create(const void *from, const char *charset)
{
  /* utf8create_len() will stop on a null byte */
	return utf8create_len(from,charset,0x7fffffff);
}

/*****************************************************************************/

int utf8fromstr(const char *from, struct codeset *codeset, utf8 *dest, unsigned int dest_size)
{
	const char *src = from;
	unsigned char c;
	int conv = 0;

	if (dest_size &lt; 1)
		return 0;

	if (!codeset)
		codeset =  (struct codeset*)list_first(&amp;codesets_list);

	for (src = from;(c = (unsigned char)*src);src++)
	{
		unsigned char *utf8_seq;
		unsigned int l;

		utf8_seq = &amp;codeset-&gt;table[c].utf8[0];

		/* Recall that the first element represents
		 * the number of characters */
		l = utf8_seq[0];
		if (dest_size &lt;= l)
			break;

		utf8_seq++;
		for(;(c = *utf8_seq);utf8_seq++)
			*dest++ = c;

		dest_size -= l;
		conv++;
	}

	*dest = 0;
	return conv;
}

/*****************************************************************************/

utf8 *utf8create_len(const void *from, const char *charset, int from_len)
{
	int dest_size = 0;
	char *dest;
	char *src = (char*)from;
	unsigned char c;
	int len;
	struct codeset *codeset = codesets_find(charset);

	if (!from) return NULL;

	if (!codeset)
	{
		if (!mystricmp(charset,&quot;utf-7&quot;))
		{
			return (utf8*)utf7ntoutf8((char *)from,from_len);
		}
		if (!mystricmp(charset,&quot;utf-8&quot;))
		{
			return (utf8*)mystrdup((char *)from);
		}
		codeset = (struct codeset*)list_first(&amp;codesets_list);
	}

	len = from_len;

	while (((c = *src++) &amp;&amp; (len--)))
		dest_size += codeset-&gt;table[c].utf8[0];

	if ((dest = (char*)malloc(dest_size+1)))
	{
		char *dest_ptr = dest;

		for (src = (char*)from;from_len &amp;&amp; (c = *src);src++,from_len--)
		{
			unsigned char *utf8_seq;

			for(utf8_seq = &amp;codeset-&gt;table[c].utf8[1];(c = *utf8_seq);utf8_seq++)
				*dest_ptr++ = c;
		}

		*dest_ptr = 0;
		return (utf8*)dest;
	}
	return NULL;
}

/*****************************************************************************/

int utf8tostr(const utf8 *str, char *dest, unsigned int dest_size, struct codeset *codeset)
{
	unsigned int i;
	struct single_convert *f;
	char *dest_iter = dest;

	if (!dest_size)
	{
		return 0;
	}

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset || !str)
	{
		*dest = 0;
		return 0;
	}

	for (i=0;i &lt; dest_size-1;i++)
	{
		unsigned char c = *str;
		if (c)
		{
			if (c &gt; 127)
			{
				unsigned int len_add = trailingBytesForUTF8[c];
				unsigned int len_str = len_add + 1;

				BIN_SEARCH(codeset-&gt;table_sorted,0,255,mystrncmp((unsigned char*)str,codeset-&gt;table_sorted[m].utf8+1,len_str),f);

				if (f) *dest_iter++ = f-&gt;code;
				else *dest_iter++ = '_';

				str += len_add;
			} else *dest_iter++ = c;

			str++;
		} else break;
	}
	*dest_iter = 0;
	return i;
}

/*****************************************************************************/

char *utf8tostrcreate(const utf8 *str, struct codeset *codeset)
{
	char *dest;
	int len;
	if (!str) return NULL;
	len = strlen((char*)str);
	if ((dest = (char*)malloc(len+1)))
		utf8tostr(str,dest,len+1,codeset);
	return dest;
}

/*****************************************************************************/

int utf8tochar(const utf8 *str, unsigned int *chr, struct codeset *codeset)
{
	struct single_convert conv;
	struct single_convert *f;
	unsigned char c;
	int len = 0;

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset) return 0;

	if ((c = *str++))
	{
		int i;

		len = trailingBytesForUTF8[c];
		conv.utf8[1] = c;

		for (i=0;i&lt;len;i++)
		{
			if (!(conv.utf8[i+2] = *str++))
			{
				/* We encountered a 0 byte although the trailing byte suggested
				 * a different length. Hence the given utf8 sequence is not
				 * considered as valid */
				*chr = 0;
				return i+1;
			}
		}
		conv.utf8[2+len] = 0;

		if ((f = (struct single_convert*)bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode)))
		{
			*chr = f-&gt;code;
		} else *chr = 0;
	} else *chr = 0;
	return len+1;
}

/*****************************************************************************/

static inline int utf8cmp_single(unsigned char *a, unsigned char *b)
{
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
	int d;

	if ((d = a[0] - b[0])) return d;
	if ((d = a[1] - b[1])) return d;
	if ((d = a[2] - b[2])) return d;
	if ((d = a[3] - b[3])) return d;
	return 0;
#else
	return (*((unsigned int *)a) - *((unsigned int *)b));
#endif
}

/*****************************************************************************/

int utf8tolower(const char *str, char *dest)
{
	unsigned char ch[4] = {0,0,0,0};
	unsigned char c;
	struct uniconv *uc;
	int bytes;
	int i;

	c = *str++;
	if (c&lt;0x80)
	{
		*dest = tolower(c);
		return 1;
	}
	bytes = trailingBytesForUTF8[c];
	if (bytes &gt; 3)
	{
		*dest++ = c;
		memcpy(dest + 1,str + 1,bytes);
		return bytes + 1;
	}

	ch[3-bytes] = c;
	for (i=bytes-1;i&gt;=0;i--)
	{
		if (!(ch[3-i] = *str++))
			return 0;
	}

	BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),utf8cmp_single(utf8_tolower_table[m].from, ch),uc);

	if (uc)
		memcpy(dest, uc-&gt;to + 3 - bytes, bytes + 1);
	else
		memcpy(dest, ch + 3 - bytes, bytes + 1);
	return bytes + 1;
}

/*****************************************************************************/

int utf8stricmp(const char *str1, const char *str2)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (1)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8stricmp_len(const char *str1, const char *str2, int len)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (len&gt;0)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;
		len--;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;

				len--;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8match(const char *haystack, const char *needle, int case_insensitive, match_mask_t *match_mask)
{
	int h, n;
	int needle_len;
	int haystack_len;

	unsigned char hc;
	unsigned char nc;

	haystack_len = strlen(haystack);
	needle_len = strlen(needle);

	h = 0;
	n = 0;
	while (h &lt; haystack_len &amp;&amp; n &lt; needle_len)
	{
		int match;
		int hbytes;
		int nbytes;

		match = 0;
		hc = haystack[h];
		nc = needle[n];

		hbytes = trailingBytesForUTF8[hc];
		nbytes = trailingBytesForUTF8[nc];

		if (hbytes == nbytes)
		{
			if (hc == nc)
			{
				int i;

				match = 1;

				for (i=0; i &lt; hbytes; i++)
				{
					if (haystack[i+1] != needle[i+1])
						match = 0;
				}
			} else
			{
				if (hbytes == 0 &amp;&amp; case_insensitive)
				{
					if (tolower(hc) == tolower(nc))
					{
						match = 1;
					}
				}
			}

			if (!match &amp;&amp; case_insensitive &amp;&amp; hbytes &gt; 0)
			{
				char hchars[6] = {0};
				char nchars[6] = {0};
				int hl, nl;

				if ((hl = utf8tolower(&amp;haystack[h], hchars)) &gt; 0 &amp;&amp;
					(nl = utf8tolower(&amp;needle[n], nchars)) &gt; 0)
				{
					if (hl == nl)
					{
						match = memcmp(hchars, nchars, nl) == 0;
					}
				}

			}
		}

		if (match)
		{
			n += nbytes + 1;
		}

		if (match_mask)
		{
			unsigned int match_pos;

			match_pos = match_bitmask_pos(h);
			if (match)
			{
				match_mask[match_pos] |= match_bitmask(h);
			} else
			{
				match_mask[match_pos] &amp;= ~match_bitmask(h);
			}
		}

		h += hbytes + 1;
	}

	if (n == needle_len)
	{
		if (match_mask)
		{
			/* Make sure that the remaining relevant positions are cleared */
			for (;h &lt; haystack_len; h++)
			{
				match_mask[match_bitmask_pos(h)] &amp;= ~match_bitmask(h);
			}
		}
		return 1;
	}
	return 0;
}

/*****************************************************************************/

char *utf8stristr(const char *str1, const char *str2)
{
	int str2_len;

	if (!str1 || !str2) return NULL;

	str2_len = strlen(str2);

	while (*str1)
	{
		if (!utf8stricmp_len(str1,str2,str2_len))
			return (char*)str1;
		str1++;
	}
	return NULL;
}

/*****************************************************************************/

const char *uft8toucs(const char *chr, unsigned int *code)
{
	unsigned char c = *chr++;
	unsigned int ucs = 0;
	int i,bytes;
	if (!(c &amp; 0x80))
	{
		*code = c;
		return chr;
	} else
	{
		if (!(c &amp; 0x20))
		{
			bytes = 2;
			ucs = c &amp; 0x1f;
		}
		else if (!(c &amp; 0x10))
		{
			bytes = 3;
			ucs = c &amp; 0xf;
		}
		else if (!(c &amp; 0x08))
		{
			bytes = 4;
			ucs = c &amp; 0x7;
		}
		else if (!(c &amp; 0x04))
		{
			bytes = 5;
			ucs = c &amp; 0x3;
		}
		else /* if (!(c &amp; 0x02)) */
		{
			bytes = 6;
			ucs = c &amp; 0x1;
		}

		for (i=1;i&lt;bytes;i++)
			ucs = (ucs &lt;&lt; 6) | ((*chr++)&amp;0x3f);
	}
	*code = ucs;
	return chr;
}

static unsigned char base64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/&quot;;
static short invbase64[128];

static unsigned char ibase64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,&quot;;
static short iinvbase64[128];

static unsigned char direct[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'(),-./:?&quot;;
static unsigned char optional[] = &quot;!\&quot;#$%&amp;*;&lt;=&gt;@[]^_`{|}&quot;;
static unsigned char spaces[] = &quot; \011\015\012&quot;;		/* space, tab, return, line feed */
static char mustshiftsafe[128];
static char mustshiftopt[128];

static int needtables = 1;

static void tabinit(void)
{
	int i, limit;

	for (i = 0; i &lt; 128; ++i)
	{
		mustshiftopt[i] = mustshiftsafe[i] = 1;
		invbase64[i] = -1;
	}
	limit = strlen((char*)direct);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[direct[i]] = mustshiftsafe[direct[i]] = 0;
	limit = strlen((char*)spaces);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[spaces[i]] = mustshiftsafe[spaces[i]] = 0;
	limit = strlen((char*)optional);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[optional[i]] = 0;
	limit = strlen((char*)base64);
	for (i = 0; i &lt; limit; ++i)
		invbase64[base64[i]] = i;

	/* that's for the modified imap utf7 stuff */
	limit = strlen((char*)ibase64);
	for (i = 0; i &lt; limit; ++i)
		iinvbase64[ibase64[i]] = i;

	needtables = 0;
}

#if __cplusplus &gt;= 201703L
#define DECLARE_BIT_BUFFER unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#else
#define DECLARE_BIT_BUFFER register unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#endif

#define BITS_IN_BUFFER bufferbits
#define WRITE_N_BITS(x, n) ((BITbuffer |= ( ((x) &amp; ~(-1L&lt;&lt;(n))) &lt;&lt; (32-(n)-bufferbits) ) ), bufferbits += (n) )
#define READ_N_BITS(n) ((buffertemp = (BITbuffer &gt;&gt; (32-(n)))), (BITbuffer &lt;&lt;= (n)), (bufferbits -= (n)), buffertemp)

/*****************************************************************************/

char *utf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '+' || c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('+',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '+')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8toiutf7(char *utf8, int sourcelen)
{
	FILE *fh;
	char *dest = NULL;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;
		int shifted = 0;
		DECLARE_BIT_BUFFER;

		while (1)
		{
			unsigned char c;
			int noshift;

			if (sourcelen)
			{
				c = *utf8;
				noshift = (c &gt;= 0x20 &amp;&amp; c &lt;= 0x7e) &amp;&amp; (c != '&amp;');
			} else
			{
				c = 0;
				noshift = 1;
			}

			if (shifted)
			{
				while (BITS_IN_BUFFER &gt;= 6)
				{
					unsigned char bits = READ_N_BITS(6);
					fputc(ibase64[bits],fh);
				}

				if (noshift)
				{
					int bits_in_buf = BITS_IN_BUFFER;

					if (bits_in_buf)
					{
						unsigned char bits = READ_N_BITS(bits_in_buf);
						bits &lt;&lt;= 6 - bits_in_buf;
						fputc(ibase64[bits],fh);
					}
					shifted = 0;
					fputc('-',fh);
				}
			}

			if (!c) break;

			if (noshift)
			{
				if (c == '&amp;')
				{
					fputs(&quot;&amp;-&quot;,fh);
				} else fputc(c,fh);
				utf8++;
				sourcelen--;
			} else
			{
				UTF8 *source = (UTF8*)utf8;
				UTF16 dest = 0;
				UTF16 *dest_ptr = &amp;dest;
				ConversionResult res;

				res = ConvertUTF8toUTF16(&amp;source, source + sourcelen, &amp;dest_ptr, dest_ptr + 1, strictConversion);
				if (res == conversionOK || res == targetExhausted)
				{
					sourcelen -= trailingBytesForUTF8[c] + 1;
					utf8 += trailingBytesForUTF8[c] + 1;

					if (!shifted)
					{
						fputc('&amp;',fh);
						shifted = 1;
					}

					WRITE_N_BITS(dest,16);
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}
	return dest;
}

/*****************************************************************************/

char *iutf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('&amp;',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '&amp;')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8topunycode(const utf8 *source, int sourcelen)
{
	enum punycode_status status;
	const utf8 *sourceend;
	char *puny;
	punycode_uint puny_len;

	punycode_uint *dest, *target;
	punycode_uint dest_len;

	if (!(dest = (punycode_uint *)malloc(sourcelen * sizeof(punycode_uint))))
		return NULL;

	target = dest;
	sourceend = source + sourcelen;

	while (source &lt; sourceend)
	{
		punycode_uint ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*(UTF8*)source];

		if (source + extraBytesToRead &gt;= sourceend)
		{
			/* source exhausted */
			free(dest);
			return NULL;
		}

		/* Do this check whether lenient or strict */
		if (!isLegalUTF8((UTF8*)source, extraBytesToRead+1))
		{
			free(dest);
			return NULL;
		}

		/*
		 * The cases all fall through.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		}
	}

	dest_len = target - dest; /* No 0 ending */
	puny_len = dest_len * 2;

	do
	{
		int strored_puny_len = puny_len;

		if (!(puny = (char*)malloc(puny_len+5)))
		{
			free(dest);
			return NULL;
		}
		status = punycode_encode(dest_len, dest, NULL /* case flags */, &amp;puny_len, puny);

		if (status == punycode_success)
		{
			puny[puny_len] = 0;
			free(dest);
			return puny;
		}
		puny_len = strored_puny_len * 2;
	} while (status == punycode_big_output);

	free(puny);
	free(dest);
	return NULL;
}
/*****************************************************************************/

utf8 *punycodetoutf8(const char *source, int sourcelen)
{
	enum punycode_status status;
	punycode_uint *utf32;
	punycode_uint length;

	length = sourcelen;

	if (!(utf32 = (punycode_uint*)malloc(sizeof(punycode_uint)*sourcelen)))
		return NULL;

	status = punycode_decode(sourcelen, source, &amp;length, utf32, NULL);
	if (status == punycode_success)
	{
		utf8 *dest = (utf8*)malloc(sourcelen * 4);
		if (dest)
		{
			UTF8 *dest_start = (UTF8*)dest;
			UTF32 *source_start = (UTF32*)utf32;

			ConvertUTF32toUTF8((UTF32**)&amp;source_start, (UTF32*)(utf32) + length, &amp;dest_start, dest_start + sourcelen * 4 - 2, strictConversion);
			*dest_start = 0;
			free(utf32);
			return dest;
		}
	}
	free(utf32);
	return NULL;
}

/*****************************************************************************/

int isascii7(const char *str)
{
	char c;
	if (!str) return 1;
	while ((c = *str++))
	{
		if (c &amp; 0x80) return 0;
	}
	return 1;
}
&lt;/pre&gt;

[https://github.com/jens-maus/yam YAM] 

&lt;pre&gt;

&lt;/pre&gt;


[https://github.com/sacredbanana/AmigaGPT AmigaGPT]

&lt;pre&gt;

&lt;/pre&gt;


From Wookiechat

Charsets: wookiechat doesnt need the incoming charset to be configured exactly anymore. When someone types weird characters, wookie will scan it for utf8 characters.. if it has those, then it'll convert it to ascii as best an Amiga can using codesets.library. if theres none, then it'll just use codesets.library Codesets_FindBest() function.

&lt;pre&gt;

&lt;/pre&gt;


== Library Calls ==

&lt;pre&gt;
TABLE OF CONTENTS

codesets.library/codesets.library
codesets.library/CodesetsSupportedA
codesets.library/CodesetsFindA
codesets.library/CodesetsFindBestA
codesets.library/CodesetsConvertStrA
codesets.library/CodesetsFreeA
codesets.library/CodesetsFreeVecPooledA
codesets.library/CodesetsSetDefaultA
codesets.library/CodesetsListCreateA
codesets.library/CodesetsListDeleteA
codesets.library/CodesetsListAddA
codesets.library/CodesetsListRemoveA
codesets.library/CodesetsUTF8CreateA
codesets.library/CodesetsUTF8ToStrA
codesets.library/CodesetsUTF8Len
codesets.library/CodesetsIsValidUTF8
codesets.library/CodesetsIsLegalUTF8
codesets.library/CodesetsIsLegalUTF8Sequence
codesets.library/CodesetsStrLenA
codesets.library/CodesetsConvertUTF16toUTF32
codesets.library/CodesetsConvertUTF16toUTF8
codesets.library/CodesetsConvertUTF32toUTF16
codesets.library/CodesetsConvertUTF32toUTF8
codesets.library/CodesetsConvertUTF8toUTF16
codesets.library/CodesetsConvertUTF8toUTF32
codesets.library/CodesetsDecodeB64A
codesets.library/CodesetsEncodeB64A


codesets.library/codesets.library

    *******************************************************************
    Copyright (c) 2005-2008 by codesets.library Open Source Team
    $Id$
    $URL$

    codesets.library is an AmigaOS shared library which provides
    functions to deal with different kind of codesets. It provides
    general character conversion routines, e.g. for converting
    from one charset (e.g. UTF8) into another (e.g. ISO-8859-1) or
    vice versa.

    codesets.library is mainly based on some code from UNICODE, some
    code from the SimpleMail project as well as some additions done
    by the codesets.library Open Source Team.

    It is released and distributed under the terms of the GNU Lesser
    General Public License (LGPL) and available free of charge.

    Please visit http://www.sf.net/projects/codesetslib/ for
    the very latest version and information regarding codesets.library.
    *******************************************************************

    For some short introduction on how to use codesets.library, the
    following pharagraph should provide a good summary. What you
    usually want to do with codesets.library is, to convert strings from
    one so-called &quot;Source Codeset&quot; into another &quot;Destination Codeset&quot;.
    The following list are only the main functions provided to
    developers, wanting to achieve this conversion in their applications:


    CodesetsSupportedA()
    --------------------

      For querying codesets library which codesets/charsets it supports
      either by its internal available charsets or by having obtained
      them from the operating system (e.g. AmigaOS4), this function
      can be used.

      E.g. in a MUI application you would do something like:

      -- cut here --
      STRPTR *array;

      if((array = CodesetsSupportedA(NULL)))
      {
        DoMethod(list, MUIM_List_Insert, array, -1, MUIV_List_Insert_Sorted);
        CodesetsFreeA(array, NULL);
      }
      -- cut here --


    CodesetsFindA()
    ---------------

      For processing/converting a specific string, you normally have to
      specify in which codeset this string has to be intepreted. For this
      purpose you have to pass a so-called &quot;Source Codeset&quot; to the main
      function of codesets.library. With the &quot;CodesetsFindA()&quot; function you
      can query codesets.library for providing you a pointer to the
      corresponding codeset structure which you afterwards will forward to
      the main conversion routines later on.

      For receiving the pointer to the Amiga-1251 codeset:
      -- cut here --
      struct codeset *cs;

      if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                            CSA_FallbackToDefault, FALSE,
                            TAG_DONE)))
      {
        ...
      }
      -- cut here --

      For querying codesets.library for the currently used system wide
      default of your running operating system:
      -- cut here --
      struct codeset *default;

      if((default = CodesetsFindA(NULL, NULL)))
      {
        ...
      }
      -- cut here --


    CodesetsConvertStrA()
    ---------------------

      The more or less most common function to use in codesets.library is
      definitly this function. It allows to convert a string from
      one &quot;Source Codeset&quot; to another &quot;Destination Codeset&quot;. It takes
      the source string converts it internally into UTF8 if necessary and
      then directly convert the UTF8 to the specified destination codeset.

      To convert a string 'str' to a destination codeset:
      -- cut here --
      STRPTR destString;

      if((destString = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                          CSA_DestCodeset,   destCodeset,
                                          CSA_Source,        str,
                                          TAG_DONE)))
      {
        ....

        CodesetsFreeA(destString, NULL);
      }
      -- cut here --

   Even if the above functions should cover most of the common functionality
   an ordinary user of codesets.library would require, it supplies a lot more
   functions which in fact we will not go into detail here but present
   certain examples in the respective documentation section of each function.

   However, if you find the documentation is still too limited or you feel
   some major functionality is missing regarding dealing with codesets,
   please let us know so that we or even you can improve it.


   Your codesets.library Open Source Team.
   February 2006


codesets.library/CodesetsSupportedA

   NAME
    CodesetsSupportedA - returns names of supported codesets

   SYNOPSIS
    array = CodesetsSupportedA(attrs);
                               A0

    STRPTR * CodesetsSupportedA(struct TagItem *);

    array = CodesetsSupported(tag1, ...);
                              A0

    STRPTR * CodesetsSupported(Tag, ...);

   FUNCTION
    Returns a NULL terminated array of the supported codeset
    names. The array _must_ be freed with CodesetsFreeA().

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

     CSA_AllowMultibyteCodesets (BOOL)
       Include multibyte codesets (UTF8, UTF16, UTF32) in the
       generated names array.
       Default: TRUE

   RESULT
    array - the names array or NULL on an error.

   EXAMPLE
    For printing out all supported codeset names:

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      int i;

      for(i=0; array[i] != NULL; i++)
        printf(&quot;%s&quot;, array[i]);

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindA

   NAME
    CodesetsFindA - finds a codeset

   SYNOPSIS
    codeset = CodesetsFindA(name, attrs);
    D0                      A0    A1

    struct codeset * CodesetsFindA(STRPTR, struct TagItem *);

    codeset = CodesetsFind(name, tag1, ...);
    D0                     A0    A1

    struct codeset * CodesetsFind(STRPTR, Tag, ...);

   FUNCTION
    Finds and returns a codeset by its name. The data behind the
    pointer should be considered read-only and must not be altered
    in any way.

   INPUTS
    name - the codeset name (or alias) to find
    attrs - a list of additional tag items. Valid items are:

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied codeset name can't be found.
        Default: TRUE

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

   RESULT
    codeset - the codeset or NULL on an error

   EXAMPLE
     E.g. for receiving the pointer to the Amiga-1251 codeset:

     -- cut here --
     struct codeset *cs;

     if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                           CSA_FallbackToDefault, FALSE,
                           TAG_DONE)))
     {
       ...
     }
     -- cut here --

     For querying codesets.library for the currently used system
     wide default of your running operating system:
     -- cut here --
     struct codeset *default;

     if((default = CodesetsFindA(NULL, NULL)))
     {
       ...
     }
     -- cut here --

   NOTE
    Please note for querying the system's default codeset the
    method of finding this codeset is highly dependent on the way
    the operating system can be queried for it. E.g. on AmigaOS4
    the default codeset is queried with updated system functions,
    but for AmigaOS3 a static list of language&lt;&gt;codeset mappings
    is used.

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindBestA

   NAME
    CodesetsFindBestA - finds the best codeset matching a
                        string content.

   SYNOPSIS
    codeset = CodesetsFindBestA(attrs);
    D0                          A0

    struct codeset * CodesetsFindBestA(struct TagItem *);

    codeset = CodesetsFindBest(tag1, ...);
    D0                         A0

    struct codeset * CodesetsFindBest(Tag, ...);

   FUNCTION
    Returns the best found codeset for the given text in the supplied
    codeset family. In case no proper codeset for the supplied source string
    could be found, NULL is returned or the default codeset if the
    CSA_FallbackToDefault attribute is set to TRUE. In addition, in case
    the CSA_ErrPtr is given, the amount of failed identifications (chars)
    are returned.

   INPUTS
    attrs - a list of tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to check just a part
        Default: string length of CSA_Source

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found errors (not identifyable chars)
        Default: NULL

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

      CSA_CodesetFamily (ULONG)
        To narrow the analyze, a user might define the codeset family
        of which the supplied text might be composed of. The reason for
        this is, that there isn't a unique identification algorithm
        which can tell the codeset out of a given text. So to narrow
        the identification, the follow values might be specified:

          CSV_CodesetFamily_Latin    - Latin codeset family (e.g. ISO-8859-X)
          CSV_CodesetFamily_Cyrillic - Cyrillic codeset family (e.g. KOI8R)

        Default: CSV_CodesetFamily_Latin

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied text couldn't be identified
        Default: FALSE

   RESULT
    codeset - the best matching codeset or NULL in case a NULL pointer
              was supplied as the source string.

   EXAMPLE
     E.g. for receiving the pointer to 'best matching' codeset matching
     a KOI8-R string:

     -- cut here --
     struct codeset *cs;
     char str[] = &quot;îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;;
     int errPtr;

     if((cs = CodesetsFindBest(CSA_Source, str,
                               CSA_ErrPtr, &amp;errPtr,
                               CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                               CSA_FallBackToDefault, FALSE,
                               TAG_DONE)))
     {
       ... should return the KOI8-R codeset ...
     }
     -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsConvertStrA

   NAME
    CodesetsConvertStrA - converts a string from one source codeset to
                          another destination codeset.

   SYNOPSIS
    dest = CodesetsConvertStrA(attrs)
    D0                         A0

    STRPTR CodesetsConvertStrA(struct TagItem *);

    dest = CodesetsConvertStr(tag1, ...);
    D0                        A0

    STRPTR CodesetsConvertStr(Tag, ...);

   FUNCTION
    The function takes source string which is encoded in a so-called
    'Source codeset' and converts it immediately into an equivalent
    string which will be encoded in the corresponding 'Destination Codeset'.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_DestCodeset (struct codeset *)
        The codeset to which the source string should be converted to.
        Default: the system's default codeset

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string
        which is returned.

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    either a pointer to the generated destination string or NULL
    on a found error.

   EXAMPLE
    To convert an ISO-8859-1 encoded string 'src' into an Amiga-1251
    equivalent 'dst' string:
    -- cut here --
    STRPTR src, dst;
    struct codeset *srcCodeset, *dstCodeset;

    srcCodeset = CodesetsFindA(&quot;ISO-8859-1&quot;, NULL);
    dstCodeset = CodesetsFindA(&quot;Amiga-1251&quot;, NULL);

    if((dst = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                 CSA_DestCodeset,   dstCodeset,
                                 CSA_Source,        src,
                                 TAG_DONE)))
    {
      ....

      CodesetsFreeA(dst, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsFreeA


codesets.library/CodesetsFreeA

   NAME
    CodesetsFreeA - frees objects previously internally allocated
                    by codesets.library

   SYNOPSIS
    CodesetsFreeA(obj, attrs)
                  A0   A1
    void CodesetsFreeA(APTR, struct TagItem *);

    CodesetsFree(obj, tag1, ...);
                 A0   A1
    void CodesetsFree(APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library. E.g. using
    functions like CodesetsSupportedA() or CodesetsConvertStrA().

   INPUTS
    obj - the object to free
    attrs - a list of additional tag items. Currently non items.

   RESULT
    no result

   EXAMPLE

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      ...

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsSupportedA
    codesets.library/CodesetsConvertStrA


codesets.library/CodesetsFreeVecPooledA

   NAME
    CodesetsFreeVecPooledA - frees objects previously allocated
                             by methods supporting CSA_Pool

   SYNOPSIS
    CodesetsFreeVecPooledA(pool, obj, attrs)
                           A0    A1   A2
    void CodesetsFreeVecPooledA(APTR, APTR, struct TagItem *);

    CodesetsFreeVecPooled(pool, obj, tag1, ...);
                          A0    A1   A2
    void CodesetsFreeVecPooled(APTR, APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library via a
    private memory pool which was previously used on codesets
    functions via the CSA_Pool tag.

   INPUTS
    pool - pointer to the private memory pool
    obj - the object to free
    attrs - a list of additional tag items. Valid tags are:

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    no result

   EXAMPLE

    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsSetDefaultA

   NAME
    CodesetsSetDefaultA - sets the default codeset, overwriting
                          the system default if necessary.

   SYNOPSIS
    codeset = CodesetsSetDefaultA(name, attrs);
                                  A0    A1

    struct codeset * CodesetsSetDefaultA(STRPTR, struct TagItem *);

    codeset = CodesetsSetDefault(name, tag1, ...);
                                 A0    A1

    struct codeset * CodesetsSetDefault(STRPTR, Tag, ...);

   FUNCTION
    Sets the default codeset to name. The codeset will be stored in
    the environment variable 'codeset_default'.

   INPUTS
    name - the name of the codeset to set as default
    attrs - a list of additional tag items. Valid items are:

      CSA_Save (BOOL)
        If TRUE the codeset will be permanently saved and survives
        a reset. Otherwise the default setting will just last until
        the next reboot.
        Default: FALSE

   RESULT
    codeset - the codeset or NULL

   NOTE
    In case the operating system supports the direct query of the
    currently active system's default codeset, this function will
    still overwrite this setting. So by using this method a user may
    overwrite all system's setting and set a global default codeset
    for his machine no matter what the OS suggests. However, in case
    your operating sytsem perfectly supports the querying of the
    system's default codeset (e.g. AmigaOS4) you are adviced to use
    this function with care - or even avoid to use it at all.

   SEE ALSO
    codesets.library/CodesetsFindA


codesets.library/CodesetsListCreateA

   NAME
    CodesetsListCreateA - creates a private, task-wise codeset list
                          and returns it to the user for further reference.

   SYNOPSIS
    list = CodesetsListCreateA(attrs);
    D0                         A0

    struct codesetList * CodesetsListCreateA(struct TagItem *);

    list = CodesetsListCreate(tag1, ...);
    D0                        A0

    struct codesetList * CodesetsListCreateA(Tag, ...);

   FUNCTION
    This function allows to create a private, task-wise codeset list by
    loading charset files from either a whole directory tree, a specific
    charset file or even by using an existing codeset structure.
    By using this function, an application might load and carry its very
    own private charsets in parallel to the internal charsets of
    codeset.library. This way each application can provide a different
    codeset list to the user without having to load and manage these
    lists on their own.

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    list - the private codeset list or NULL on an error condition

   NOTE
    For convienence, if no tag item attribute at all is supplied to the
    function, codesets.library will try to load charsets from the
    corresponding &quot;PROGDIR:Charsets&quot; directoy and add found codeset to
    the list. However, in case a tag item is specified (no matter what
    kind) the PROGDIR: scanning will be omitted.

   EXAMPLE
    For loading all found charset files from PROGDIR:Charsets:

    -- cut here --
    struct codesetList *csList;

    if((csList = CodesetsListCreateA(NULL)))
    {
      STRPTR codesetArray = CodesetsSupported(CSA_CodesetList, csList,
                                              TAG_DONE);

      // codesetsArray should now also carry our private
      // codesets from PROGDIR:Charsets
      ...

      CodesetsListDeleteA(CSA_CodesetList, csList,
                          TAG_DONE);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA
    codesets.library/CodesetsListSupportedA
    codesets.library/CodesetsListFindA
    codesets.library/CodesetsListFindBestA


codesets.library/CodesetsListDeleteA

   NAME
    CodesetsListDeleteA - deletes/frees all resources of previously created
                          private codeset lists.

   SYNOPSIS
    result = CodesetsListDeleteA(attrs);
    D0                           A0

    BOOL CodesetsListDeleteA(struct TagItem *);

    result = CodesetsListDelete(tag1, ...);
    D0                          A0

    BOOL CodesetsListDelete(Tag, ...);

   FUNCTION
    This function deletes all resources (also the contained codeset
    structures per default) and frees the memory of previously allocated
    private codeset lists.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        Pointer to a previously created, private codeset list whos
        resources should be freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all contained codesets should also be freed/deleted,
        otherwise just frees the list object itself.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Please note that if you added an explicit codeset structure to more
    than two private codeset lists you may run into problems with you
    don't take care of this yourself. This is a dumb function which just
    walks through the list and frees all resources. Set CSA_FreeCodesets
    to FALSE in case you just want to free the list object.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA


codesets.library/CodesetsListAddA

   NAME
    CodesetsListAddA - allows to add additional codesets to an already
                       existing private codeset list previously created with
                       CodesetsListCreateA().

   SYNOPSIS
    result = CodesetsListAddA(attrs);
    D0                        A0

    BOOL CodesetsListAddA(struct TagItem *);

    result = CodesetsListAdd(tag1, ...);
    D0                       A0

    BOOL CodesetsListAdd(Tag, ...);

   FUNCTION
    This function allows to add additional codesets to an already existing
    private codeset list. Either codesets themself may be added directly, or
    the path to either a file or a directory may be specified from which
    additional codesets may be loaded from known charset files.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Be careful when adding one codeset to more than one codeset list as
    you may run into problems when freeing the list afterwards.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsListRemoveA

   NAME
    CodesetsListRemoveA - removes a single or multiple codesets from a
                          previously created codeset list.

   SYNOPSIS
    result = CodesetsListRemoveA(attrs);
    D0                           A0

    BOOL CodesetsListRemoveA(struct TagItem *);

    result = CodesetsListRemove(tag1, ...);
    D0                          A0

    BOOL CodesetsListRemove(Tag, ...);

   FUNCTION
    This function allows to remove single or multiple codesets from a
    previously created codeset list. The removed codeset structures will
    also be freed/deleted per default.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        Pointer to a codeset structure which should be removed from
        its corresponding list. Per default its resources will also
        be internally freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all supplied codesets should also be freed/deleted,
        otherwise the codesets will just be removed from their lists.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    The function will automatically prevent removal of codesets from the
    internal codeset list of codesets.library and will return FALSE in
    case a user tried to remove a codeset from the internal list.

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsUTF8CreateA

   NAME
    CodesetsUTF8CreateA - creates an UTF8 compliant string
                          interpretation out of a supplied source
                          string.


   SYNOPSIS
    utf8 = CodesetsUTF8CreateA(attrs);
                               A0
    UTF8 * CodesetsUTF8CreateA(struct TagItem *);

    utf8 = CodesetsUTF8Create(tag1, ...);
                              A0
    UTF8 * CodesetsUTF8Create(Tag, ...);


   FUNCTION
    Creates an UTF8 from a string which is encoded in specified
    codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole utf8. If CSA_Dest can't
        contain the utf8, a brand new buffer is allocated. If
        CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the utf8 string

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the UTF8 a new buffer is allocated
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, utf8, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(utf8, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    utf8 - the utf8 string or NULL
           If CSA_DestHook is used always NULL.
           If CSA_DestHook is not used NULL means failure
           to allocate mem.

   EXAMPLE
    The shortest invocation is:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    In case you want to use your pool to allocate mem:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If your pool is to be arbitrated via a semaphore:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;
    struct SignalSemaphore *sem;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  CSA_PoolSem,    sem,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If you want to use your own buffer to reduce mem
    allocation:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[256];

    if((utf8 = CodesetsUTF8Create(CSA_Source,  str,
                                  CSA_Dest,    buf,
                                  CSA_DestLen, sizeof(buf),
                                  TAG_DONE)))
    {
        ...

        if(utf8 != buf)
          CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    If your string are max MAXLEN chars long (e.g. image to be
    in a MUI application and you know the max size of your
    string gadgets), you should better supply your own buffer:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[MAXSIZE*6+1];

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  CSA_Dest,   buf,
                                  CSA_Dest,   sizeof(buf),
                                  TAG_DONE)))
    {
        ...
    }
    -- cut here --


    If you strings are very large and so you are sure there is
    no mem for them and or you have your own reasons to do
    that:
    -- cut here --
    static ULONG ASM SAVEDS
    destFun(REG(a0, struct Hook *hook),
            REG(a2, struct convertMsg *msg),
            REG(a1, STRPTR buf))
    {
      printf(&quot;[%3ld] [%s]\n&quot;,msg-&gt;len,buf);
      if(msg-&gt;state == CSV_End)
        printf(&quot;\n&quot;);

      return 0;
    }

    struct Hook dest;
    dest.h_Entry = (HOOKFUNC)destFun;

    CodesetsUTF8Create(CSA_Source,    str,
                       CSA_DestHook,  &amp;dest,
                       TAG_DONE);
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8ToStrA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8ToStrA

   NAME
    CodesetsUTF8ToStrA - converts an UTF8 encoded string into
                         a specified destination codeset.


   SYNOPSIS
    str = CodesetsUTF8ToStrA(attrs);
    D0                       A0

    STRPTR CodesetsUTF8ToStrA(attrs);

    str = CodesetsUTF8ToStr(tag1, ...);
    D0                      A0

    STRPTR CodesetsUTF8ToStr(Tag,...);


   FUNCTION
    Convert an utf8 string to a specified codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source. Must be &gt; 0 or the function returns
        NULL.
        Default: string length of CSA_Source - strlen()

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole converted string. If CSA_Dest
        can't contain the output string, a brand new buffer is allocated.
        If CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestCodeset (struct codeset *)
        The codeset to which the UTF8 string should be encoded to.
        Default: the system's default codeset

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string.

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the output string, a new buffer is allocated.
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, string, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(string, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found issues (number of not convertable chars)
        Default: NULL

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    str - the string or NULL
          If CSA_DestHook is used always NULL.
          If CSA_DestHook is not used NULL means failure
          to allocate mem.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8Len

   NAME
    CodesetsUTF8Len - returns the length of a supplied utf8 string.

   SYNOPSIS
    len = CodesetsUTF8Len(utf8);
    D0                    A0

    ULONG CodesetsUTF8Len(UTF8 *);

   FUNCTION
    Returns the amount of real characters stored in a supplied UTF8
    string. This is _NOT_ the space required to store the UTF8 string,
    it is the actual number of _real_ character the UTF8 represents.

   INPUTS
    utf8 - pointer to the UTF8 string generated by the internal
           functions of codesets.library

   RESULT
    len - length of utf8

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsValidUTF8

   NAME
    CodesetsIsValidUTF8 - tells if a supplied standard string is meant to
                          carry a perfectly valid UTF8 sequence

   SYNOPSIS
    result = CodesetsIsValidUTF8(str);
    D0                           A0

    BOOL CodesetsIsValidUTF8(STRPTR);

   FUNCTION
    Returns TRUE in case the supplied string only contains char sequences
    which are compatible to the UTF8 standard.

   INPUTS
    str - a standard STRPTR string.

   RESULT
    result - TRUE in case the string conatins valid UTF8 data.

   NOTE
    This function uses the common 'GOOD_UCS' macro together with parsing
    the whole string. This means that it will only return TRUE in case
    the supplied string only contains UTF8 sequences. A mixture of UTF8
    and non-UTF8 sequences will result in the function returning FALSE.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8

   NAME
    CodesetsIsLegalUTF8 - check a UTF8 sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8(source, length);
                              A0      D0

    ULONG CodesetsIsLegalUTF8(UTF8 *, ULONG);


   FUNCTION
    Checks if source is a valid UTF8 sequence generated
    by the internal functions of codesets.library

   INPUTS
    source - the char sequence to check
    length - size of source

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8Sequence

   NAME
    CodesetsIsLegalUTF8Sequence - check a char sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8Sequence(source, end);
                                      A0      A1

    ULONG CodesetsIsLegalUTF8(UTF8 *, UTF8 *);

   FUNCTION
    Check if source is a valid UTF8 sequence within the
    source and end boundaries.

   INPUTS
    source - the char sequence to check
    end - pointer to the end of the sequence to check

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsStrLenA

   NAME
    CodesetsStrLenA - returns the length of the source string
                      in case it will be converted to an UTF8
                      string.

   SYNOPSIS
    len = CodesetsStrLenA(str, attrs)
                          A0   A1

    ULONG CodesetsStrLenA(STRPTR, struct TagItem *);

    len = CodesetsStrLen(str, tag1, ...);
                         A0   A1

    ULONG CodesetsStrLen(STRPTR, Tag, ...);

   FUNCTION
    Return the length (size) of str in case it will be converted to
    an UTF8 compliant string.

   INPUTS
    str - the string to obtain length of
    attrs - a list of additional tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        The codeset the source string is encoded in.
        Default: the system's default codeset

      CSA_SourceLen (ULONG)
        The length of str
        Default: string length of CSA_Source

   RESULT
    len - the length of the string if it will be converted to
          an UTF8 string.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA


codesets.library/CodesetsConvertUTF16toUTF32

   NAME
    CodesetsConvertUTF16toUTF32 - converts from UTF16 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF32(const UTF16 **,const UTF16 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF16toUTF8

   NAME
    CodesetsConvertUTF16toUTF8 - converts from UTF16 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF8(const UTF16 **,const UTF16 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF8.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF16

   NAME
    CodesetsConvertUTF32toUTF16 - converts from UTF32 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF16(const UTF32 **,const UTF32 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF8

   NAME
    CodesetsConvertUTF32toUTF8 - converts from UTF32 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF8(const UTF32 **,const UTF32 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF16

   NAME
    CodesetsConvertUTF8toUTF16 - converts from UTF8 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF16(const UTF8 **,const UTF8 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF32

   NAME
    CodesetsConvertUTF8toUTF32 - converts from UTF8 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF32(const UTF8 **,const UTF8 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsDecodeB64A

   NAME
    CodesetsDecodeB64A - decodes a supplied base64 encoded string
                         or file into plain text charwise.

   SYNOPSIS
    res = CodesetsDecodeB64A(attrs);
    D0                       A0

    ULONG CodesetsDecodeB64A(struct TagItem *);

    res = CodesetsDecodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsDecodeB64A(Tag, ....);

   FUNCTION
    Decodes a string or a complete base64 encoded file to a
    plain text buffer or also a destination file

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to decode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64FLG_NtCheckErr (BOOL)
        Don't stop on error.

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be still be encoded to.

   SEE ALSO
    codesets.library/CodesetsEncodeB64A


codesets.library/CodesetsEncodeB64A

   NAME
    CodesetsEncodeB64A - encodes a string or whole file
                         to base64

   SYNOPSIS
    res = CodesetsEncodeB64A(attrs);
    D0                       A0

    ULONG CodesetsEncodeB64A(struct TagItem *);

    res = CodesetsEncodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsEncodeB64(Tag, ....);

   FUNCTION
    Encodes the supplied string or file to either a whole
    buffer or also to a file.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to encode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString. Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64MaxLineLen (ULONG)
        Maximum length of encoded lines. 0&lt;v&lt;256
        Default: 72

      CSA_B64Unix (ULONG)
        If TRUE eol is \n (LF), otherwise \r\n (CRLF).
        Default: TRUE

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be encoded to.

   SEE ALSO
    codesets.library/CodesetsDecodeB64A

&lt;/pre&gt;</text>
      <sha1>ny08qwdys9kn4l5qr4d2v1p8gcqxb02</sha1>
    </revision>
    <revision>
      <id>4669773</id>
      <parentid>4669771</parentid>
      <timestamp>2026-09-12T17:07:04Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669773</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129283" sha1="m2rihzw4cvdpvu6y0e7cl05p9c6boo6" xml:space="preserve">{{ArosNav}}

==Introduction==

Character set (charsets) encoding is the process of assigning numbers to graphical characters, especially the written characters of human language

Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251      – Cyrillic (Amiga)
    ISO-8859-1      – Latin 1 aka Western European ASCII based 
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2      – Latin-2 aka Central/East European
    ISO-8859-3      – South European
    ISO-8859-4      – North European
    ISO-8859-5      – Slavic languages
    ISO-8859-9      – Turkish
    ISO-8859-15     – West European II
    ISO-8859-16     – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)

Windows-1252 was first character set in Windows. It was a copy of ASCII, but used 8-bits to represent 256 different characters (international letters). Windows-1252 is supported by all browsers.
&lt;/pre&gt;


==Source Code==

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;exec/libraries.h&gt;
#include &lt;libraries/codesets.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;proto/exec.h&gt;

#include &lt;stdio.h&gt;

/* This is just a very quickly written test, not a full-featured convertor */
#define BUF_SIZE 102400

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace *ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

struct codeset *srcCodeset;
struct codeset *destCodeset;

int main(int argc, char **argv)
{
  char *buf, *destbuf;
  ULONG destlen;
  FILE *f;

  if (argc &lt; 4)
  {
    fprintf(stderr, &quot;Usage: %s &lt;source codeset&gt; &lt;destination codeset&gt; &lt;source file&gt;\n&quot;, argv[0]);
    return 0;
  }
  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
     GETINTERFACE(ICodesets, CodesetsBase))
  {
    srcCodeset = CodesetsFind(argv[1], CSA_FallbackToDefault, FALSE, TAG_DONE);
    if (srcCodeset)
    {
      destCodeset = CodesetsFind(argv[2], CSA_FallbackToDefault, FALSE, TAG_DONE);
      if (destCodeset)
      {
        buf = AllocMem(BUF_SIZE, MEMF_CLEAR);

        if (buf)
        {
          f = fopen(argv[3], &quot;r&quot;);
          if (f)
          {
            fread(buf, BUF_SIZE-1, 1, f);
            fclose(f);
            destbuf = CodesetsConvertStr(CSA_SourceCodeset, (IPTR)srcCodeset,
                                         CSA_DestCodeset, (IPTR)destCodeset,
                                         CSA_Source, (IPTR)buf,
                                         CSA_DestLenPtr, (IPTR)&amp;destlen,
                                         TAG_DONE);
            if (destbuf)
            {
              fprintf(stderr, &quot;Result length: %u\n&quot;, (unsigned int)destlen);
              fwrite(destbuf, destlen, 1, stdout);
              fputc('\n', stderr);
              CodesetsFreeA(destbuf, NULL);
            }
          else
            fprintf(stderr, &quot;Failed to convert text!\n&quot;);
          }
          FreeMem(buf, BUF_SIZE);
        }
        else
          fprintf(stderr, &quot;Failed to allocate %d bytes for buffer\n&quot;, BUF_SIZE);
      }
      else
        fprintf(stderr, &quot;Unknown destination codeset %s\n&quot;, argv[2]);
    }
    else
      fprintf(stderr, &quot;Unknown source codeset %s\n&quot;, argv[1]);

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
  }
  else
    fprintf(stderr, &quot;Failed to open codesets.library!\n&quot;);

  return 0;
}
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;proto/exec.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define ISO8859_1_STR &quot;Schmöre bröd, schmöre bröd, bröd bröd bräd.&quot;
#define CP1251_STR    &quot;1251 êîäèðîâêà äëÿ ïðèìåðà.&quot;
#define ASCII_STR     &quot;latin 1 bla bla bla.&quot;
#define KOI8R_STR     &quot;koi îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace* ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

int main(void)
{
  int res;

  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
      GETINTERFACE(ICodesets, CodesetsBase))
  {
    IPTR errNum = 0;
    struct codeset *cs;

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ISO8859_1_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              TAG_DONE)))
    {
      printf(&quot;Identified ISO8859_1_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ISO8859_1_STR));
    }
    else
      printf(&quot;couldn't identify ISO8859_1_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)CP1251_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified CP1251_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(CP1251_STR));
    }
    else
      printf(&quot;couldn't identify CP1251_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ASCII_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified ASCII_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ASCII_STR));
    }
    else
      printf(&quot;couldn't identify ASCII_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)KOI8R_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified KOI8R_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(KOI8R_STR));
    }
    else
      printf(&quot;couldn't identify KOI8R_STR!\n&quot;);

    res = 0;

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
    CodesetsBase = NULL;
  }
  else
  {
    printf(&quot;can't open %s %d+\n&quot;,CODESETSNAME,CODESETSVER);
    res = 20;
  }

  return res;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


From [https://github.com/sba1/simplemail SimpleMail] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************
 SimpleMail - Copyright (C) 2000 Hynek Schlawack and Sebastian Bauer

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
***************************************************************************/

/**
 * @brief Support of codesets.
 *
 * @file codesets.c
 */

#include &quot;codesets.h&quot;

#include &lt;ctype.h&gt;
#include &lt;dirent.h&gt; /* dir stuff */
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;unistd.h&gt;

#include &quot;codesets_table.h&quot;
#include &quot;debug.h&quot;
#include &quot;punycode.h&quot;
#include &quot;smintl.h&quot;
#include &quot;support_indep.h&quot;

/* from ConvertUTF.h */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8.  Header file.

    Several funtions are included here, forming a complete set of
    conversions between the three formats.  UTF-7 is not included
    here, but is handled in a separate source file.

    Each of these routines takes pointers to input buffers and output
    buffers.  The input buffers are const.

    Each routine converts the text between *sourceStart and sourceEnd,
    putting the result into the buffer between *targetStart and
    targetEnd. Note: the end pointers are *after* the last item: e.g.
    *(sourceEnd - 1) is the last item.

    The return result indicates whether the conversion was successful,
    and if not, whether the problem was in the source or target buffers.
    (Only the first encountered problem is indicated.)

    After the conversion, *sourceStart and *targetStart are both
    updated to point to the end of last text successfully converted in
    the respective buffers.

    Input parameters:
	sourceStart - pointer to a pointer to the source buffer.
		The contents of this are modified on return so that
		it points at the next thing to be converted.
	targetStart - similarly, pointer to pointer to the target buffer.
	sourceEnd, targetEnd - respectively pointers to the ends of the
		two buffers, for overflow checking only.

    These conversion functions take a ConversionFlags argument. When this
    flag is set to strict, both irregular sequences and isolated surrogates
    will cause an error.  When the flag is set to lenient, both irregular
    sequences and isolated surrogates are converted.

    Whether the flag is strict or lenient, all illegal sequences will cause
    an error return. This includes sequences such as: &lt;F4 90 80 80&gt;, &lt;C0 80&gt;,
    or &lt;A0&gt; in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
    must check for illegal sequences.

    When the flag is set to lenient, characters over 0x10FFFF are converted
    to the replacement character; otherwise (when the flag is set to strict)
    they constitute an error.

    Output parameters:
	The value &quot;sourceIllegal&quot; is returned from some routines if the input
	sequence is malformed.  When &quot;sourceIllegal&quot; is returned, the source
	value will point to the illegal value that caused the problem. E.g.,
	in UTF-8 when a sequence is malformed, it points to the start of the
	malformed sequence.

    Author: Mark E. Davis, 1994.
    Rev History: Rick McGowan, fixes &amp; updates May 2001.

------------------------------------------------------------------------ */

/* ---------------------------------------------------------------------
    The following 4 definitions are compiler-specific.
    The C standard does not guarantee that wchar_t has at least
    16 bits, so wchar_t is no less portable than unsigned short!
    All should be unsigned values to avoid sign extension during
    bit mask &amp; shift operations.
------------------------------------------------------------------------ */

typedef unsigned long	UTF32;	/* at least 32 bits */
typedef unsigned short	UTF16;	/* at least 16 bits */
typedef unsigned char	UTF8;	/* typically 8 bits */
typedef unsigned char	Boolean; /* 0 or 1 */

/* Some fundamental constants */
#define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
#define UNI_MAX_BMP (UTF32)0x0000FFFF
#define UNI_MAX_UTF16 (UTF32)0x0010FFFF
#define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF

typedef enum {
	conversionOK, 		/* conversion successful */
	sourceExhausted,	/* partial character in source, but hit end */
	targetExhausted,	/* insuff. room in target for conversion */
	sourceIllegal,		/* source sequence is illegal/malformed */
  sourceCorrupt,    /* source contains invalid UTF-7 */ /* addded */
} ConversionResult;

typedef enum {
	strictConversion = 0,
	lenientConversion
} ConversionFlags;

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags);

static Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);

/* --------------------------------------------------------------------- */

int utf8islegal(const char *source, const char *sourceend)
{
	return isLegalUTF8Sequence((const UTF8*)source, (const UTF8*)sourceend);
}

/* --------------------------------------------------------------------- */

/* ConvertUTF.c */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8. Source code file.
	Author: Mark E. Davis, 1994.
	Rev History: Rick McGowan, fixes &amp; updates May 2001.

    See the header file &quot;ConvertUTF.h&quot; for complete documentation.

------------------------------------------------------------------------ */


/*#include &quot;ConvertUTF.h&quot;*/
/*#ifdef CVTUTF_DEBUG*/
#include &lt;stdio.h&gt;
/*#endif*/

static const int halfShift	= 10; /* used for shifting by 10 bits */

static const UTF32 halfBase	= 0x0010000UL;
static const UTF32 halfMask	= 0x3FFUL;

#define UNI_SUR_HIGH_START	(UTF32)0xD800
#define UNI_SUR_HIGH_END	(UTF32)0xDBFF
#define UNI_SUR_LOW_START	(UTF32)0xDC00
#define UNI_SUR_LOW_END		(UTF32)0xDFFF
#define false			0
#define true			1

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		ch = *source++;
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF32* target = *targetStart;
	UTF32 ch, ch2;
	while (source &lt; sourceEnd) {
		ch = *source++;
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			/* an unpaired low surrogate */
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		*target++ = ch;
	}
	*sourceStart = source;
	*targetStart = target;
#ifdef CVTUTF_DEBUG
if (result == sourceIllegal) {
    fprintf(stderr, &quot;ConvertUTF16toUTF32 illegal seq 0x%04x,%04x\n&quot;, ch, ch2);
    fflush(stderr);
}
#endif
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Index into the table below with the first byte of a UTF-8 sequence to
 * get the number of trailing bytes that are supposed to follow it.
 */

static const char trailingBytesForUTF8[256] = {
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
	2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, 3,3,3,3,3,3,3,3,4,4,4,4,5,5,5,5
};

/*
 * Magic values subtracted from a buffer value during UTF8 conversion.
 * This table contains as many values as there might be trailing bytes
 * in a UTF-8 sequence.
 */
static const UTF32 offsetsFromUTF8[6] = { 0x00000000UL, 0x00003080UL, 0x000E2080UL,
					 0x03C82080UL, 0xFA082080UL, 0x82082080UL };

/*
 * Once the bits are split out into bytes of UTF-8, this is a mask OR-ed
 * into the first byte, depending on how many bytes follow.  There are
 * as many entries in this table as there are UTF-8 sequence types.
 * (I.e., one byte sequence, two byte... six byte sequence.)
 */
static const UTF8 firstByteMark[7] = { 0x00, 0x00, 0xC0, 0xE0, 0xF0, 0xF8, 0xFC };

/* --------------------------------------------------------------------- */

/* The interface converts a whole buffer to avoid function-call overhead.
 * Constants have been gathered. Loops &amp; conditionals have been removed as
 * much as possible for efficiency, in favor of drop-through switches.
 * (See &quot;Note A&quot; at the bottom of the file for equivalent code.)
 * If your compiler supports it, the &quot;isLegalUTF8&quot; call can be turned
 * into an inline function.
 */

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* If we have a surrogate pair, convert to UTF32 first. */
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			UTF32 ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Utility routine to tell whether a sequence of bytes is legal UTF-8.
 * This must be called with the length pre-determined by the first byte.
 * If not calling this from ConvertUTF8to*, then the length can be set by:
 *	length = trailingBytesForUTF8[*source]+1;
 * and the sequence is illegal right away if there aren't that many bytes
 * available.
 * If presented with a length &gt; 4, this returns false.  The Unicode
 * definition of UTF-8 goes up to 4-byte sequences.
 */

static Boolean isLegalUTF8(const UTF8 *source, int length) {
	UTF8 a;
	const UTF8 *srcptr = source+length;
	switch (length) {
	default: return false;
		/* Everything else falls through when &quot;true&quot;... */
	case 4: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 3: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 2: if ((a = (*--srcptr)) &gt; 0xBF) return false;
		switch (*source) {
		    /* no fall-through in this inner switch */
		    case 0xE0: if (a &lt; 0xA0) return false; break;
		    case 0xF0: if (a &lt; 0x90) return false; break;
		    case 0xF4: if (a &gt; 0x8F) return false; break;
		    default:  if (a &lt; 0x80) return false;
		}
    	case 1: if (*source &gt;= 0x80 &amp;&amp; *source &lt; 0xC2) return false;
		if (*source &gt; 0xF4) return false;
	}
	return true;
}

/* --------------------------------------------------------------------- */

/*
 * Exported function to return whether a UTF-8 sequence is legal or not.
 * This is not used here; it's just exported.
 */
Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd) {
	int length = trailingBytesForUTF8[*source]+1;
	if (source+length &gt; sourceEnd) {
	    return false;
	}
	return isLegalUTF8(source, length);
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
				source -= extraBytesToRead; /* return to the start */
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* surrogates of any stripe are not legal UTF32 characters */
		if (flags == strictConversion ) {
			if ((ch &gt;= UNI_SUR_HIGH_START) &amp;&amp; (ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF32* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		} else {
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* ---------------------------------------------------------------------

	Note A.
	The fall-through switches in UTF-8 reading code save a
	temp variable, some decrements &amp; conditionals.  The switches
	are equivalent to the following loop:
		{
			int tmpBytesToRead = extraBytesToRead+1;
			do {
				ch += *source++;
				--tmpBytesToRead;
				if (tmpBytesToRead) ch &lt;&lt;= 6;
			} while (tmpBytesToRead &gt; 0);
		}
	In UTF-8 writing code, the switches on &quot;bytesToWrite&quot; are
	similarly unrolled loops.

   --------------------------------------------------------------------- */

/* Some code has been taken from the ConvertUTF7.c file (the utf7 stuff below),
   this is the copyright notice */

/* ================================================================ */
/*
File:   ConvertUTF7.c
Author: David B. Goldsmith
Copyright (C) 1994, 1996 IBM Corporation All rights reserved.
Revisions: Header update only July, 2001.

This code is copyrighted. Under the copyright laws, this code may not
be copied, in whole or part, without prior written consent of IBM Corporation.

IBM Corporation grants the right to use this code as long as this ENTIRE
copyright notice is reproduced in the code.  The code is provided
AS-IS, AND IBM CORPORATION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT
WILL IBM CORPORATION BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING,
WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY
LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THIS CODE, EVEN
IF IBM CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATION MAY NOT APPLY TO YOU.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the
government is subject to restrictions as set forth in subparagraph
(c)(l)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and FAR 52.227-19.

This code may be protected by one or more U.S. and International
Patents.

*/


/* ------------------------------------- */

struct list codesets_list;

/**************************************************************************
 Returns the supported codesets as an null terminated string array
**************************************************************************/
char **codesets_supported(void)
{
	static char **array;

	if (array) return array;

	if ((array = (char**)malloc(sizeof(char*)*(list_length(&amp;codesets_list)+1))))
	{
		struct codeset *code;
		int i;

		SM_DEBUGF(15,(&quot;%ld supported Codesets:\n&quot;,list_length(&amp;codesets_list)));

		code = (struct codeset*)list_first(&amp;codesets_list);
		i = 0;

		while (code)
		{
			SM_DEBUGF(15,(&quot;  %p next=%p prev=%p list=%p name=%p %s alt=%p char=%p\n&quot;,code,code-&gt;node.next,code-&gt;node.prev,code-&gt;node.list,code-&gt;name,code-&gt;name,code-&gt;alt_name,code-&gt;characterization));
			array[i++] = code-&gt;name;
			code = (struct codeset*)node_next(&amp;code-&gt;node);
		}
		array[i] = NULL;
	}
	return array;
}

/**************************************************************************
 The compare function
**************************************************************************/
static int codesets_cmp_unicode(const void *arg1, const void *arg2)
{
	char *a1 = (char*)((struct single_convert*)arg1)-&gt;utf8 + 1;
	char *a2 = (char*)((struct single_convert*)arg2)-&gt;utf8 + 1;
	return (int)strcmp(a1,a2);
}

/**
 * Reads the codeset table from the given filename and adds it.
 *
 * @param name
 * @return
 */
static int codesets_read_table(char *name)
{
	char buf[512];

	FILE *fh = fopen(name,&quot;r&quot;);

	if (fh)
	{
		struct codeset *codeset;
		if ((codeset = (struct codeset*)malloc(sizeof(struct codeset))))
		{
			int i;
			memset(codeset,0,sizeof(struct codeset));

			for (i=0;i&lt;256;i++)
				codeset-&gt;table[i].code = codeset-&gt;table[i].ucs4 = i;

			while (myreadline(fh,buf))
			{
				char *result;
				if ((result = get_key_value(buf,&quot;Standard&quot;))) codeset-&gt;name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;AltStandard&quot;))) codeset-&gt;alt_name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;ReadOnly&quot;))) codeset-&gt;read_only = !!atoi(result);
				else if ((result = get_key_value(buf,&quot;Characterization&quot;)))
				{
					if ((result[0] == '_') &amp;&amp; (result[1] == '(') &amp;&amp; (result[2] == '&quot;'))
					{
						char *end = strchr(result+3,'&quot;');
						if (end)
						{
							char *txt = mystrndup(result+3,end-(result+3));
							if (txt) codeset-&gt;characterization = mystrdup(_(txt));
							free(txt);
						}
					}
				} else
				{
					char *p = buf;
					int fmt2 = 0;

					if ((*p == '=') || (fmt2 = ((*p == '0') || (*(p+1)=='x'))))
					{
						p++;
						p += fmt2;

						i = strtol(p,&amp;p,16);
						if (i &gt; 0 &amp;&amp; i &lt; 256)
						{
							while (isspace((unsigned char)*p)) p++;

							if (!mystrnicmp(p,&quot;U+&quot;,2))
							{
								p += 2;
								codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,16);
							} else
							{
								if (*p!='#') codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,0);
							}
						}
					}
				}
			}

			for (i=0;i&lt;256;i++)
			{
				UTF32 src = codeset-&gt;table[i].ucs4;
				UTF32 *src_ptr = &amp;src;
				UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];
				ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
				*dest_ptr = 0;
				codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
			}

			memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
			qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
			list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);
		}
		fclose(fh);
	}
	return 1;
}

/*****************************************************************************/

int codesets_init(void)
{
	int i;
	struct codeset *codeset;
	UTF32 src;

	SM_ENTER;

	list_init(&amp;codesets_list);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 0;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1 + Euro&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European (with EURO)&quot;));
	codeset-&gt;read_only = 1;

	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i==164) src = 0x20AC; /* the EURO sign */
		else src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-2&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Central/East European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_2_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-3&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_3_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-4&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;North European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_4_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;KOI8-R&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Russian&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0x80) src = i;
		else src = koi8r_to_ucs4[i-0x80];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-5&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Slavic languages&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_5_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-9&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Turkish&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_9_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-15&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European II&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_15_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-16&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South-Eastern European&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_16_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amigapl_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amiga1251_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	SM_DEBUGF(15,(&quot;%ld internal charsets\n&quot;,list_length(&amp;codesets_list)));

	{
		/* dynamicaly loaded */

		DIR *dfd; /* directory descriptor */
		struct dirent *dptr; /* dir entry */
		char path[380];

		getcwd(path, sizeof(path));
		if (chdir(SM_CHARSET_DIR) != -1)
		{
			if ((dfd = opendir(SM_CURRENT_DIR)))
			{
				while ((dptr = readdir(dfd)) != NULL)
				{
					if (!strcmp(&quot;.&quot;,dptr-&gt;d_name) || !strcmp(&quot;..&quot;,dptr-&gt;d_name)) continue;
					SM_DEBUGF(15,(&quot;Loading \&quot;%s\&quot; charset\n&quot;,dptr-&gt;d_name,list_length(&amp;codesets_list)));
					codesets_read_table(dptr-&gt;d_name);
				}
				closedir(dfd);
			}
			chdir(path);
		}
	}

	SM_RETURN(1,&quot;%ld&quot;);
}

/*****************************************************************************/

void codesets_cleanup(void)
{
	struct codeset *codeset;

	while ((codeset = (struct codeset*)list_remove_tail(&amp;codesets_list)))
	{
		free(codeset-&gt;name);
		free(codeset-&gt;alt_name);
		free(codeset-&gt;characterization);
		free(codeset);
	}
}

/*****************************************************************************/

struct codeset *codesets_find(const char *name)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);

	/* Return ISO-8859-1 as default codeset */
	if (!name) return codeset;

	while (codeset)
	{
		if (!mystricmp(name,codeset-&gt;name) || !mystricmp(name,codeset-&gt;alt_name)) return codeset;
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}
	return NULL;
}

/*****************************************************************************/

int codesets_unconvertable_chars(struct codeset *codeset, const char *text, int text_len)
{
	struct single_convert conv;
	const char *text_ptr = text;
	int i;
	int errors = 0;

	for (i=0;i &lt; text_len;i++)
	{
		unsigned char c = *text_ptr++;
		if (c)
		{
			int len = trailingBytesForUTF8[c];
			conv.utf8[1] = c;
			strncpy((char*)&amp;conv.utf8[2],text_ptr,len);
			conv.utf8[2+len] = 0;
			text_ptr += len;

			if (!bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode))
				errors++;
		} else break;
	}

	return errors;
}

/*****************************************************************************/

struct codeset *codesets_find_best(const char *text, int text_len, int *error_ptr)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);
	struct codeset *best_codeset = NULL;
	int best_errors = text_len;

	while (codeset)
	{
		if (!codeset-&gt;read_only)
		{
			int errors = codesets_unconvertable_chars(codeset, text, text_len);

			if (errors &lt; best_errors)
			{
				best_codeset = codeset;
				best_errors = errors;
			}
			if (!best_errors) break;
		}
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}

	if (!best_codeset) best_codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (error_ptr) *error_ptr = best_errors;

	return best_codeset;
}

/*****************************************************************************/

int utf8len(const utf8 *str)
{
	int len ;
	unsigned char c;

	if (!str) return 0;
	len = 0;

	while ((c = *str++))
	{
		len++;
		str += trailingBytesForUTF8[c];
	}

	return len;
}

/*****************************************************************************/

utf8 *utf8dup(const utf8 *str)
{
	return (utf8*)mystrdup((char*)str);
}

/*****************************************************************************/

int utf8realpos(const utf8 *str, int pos)
{
	const utf8 *str_save = str;
	unsigned char c;

	if (!str) return 0;

	while (pos &amp;&amp; (c = *str))
	{
		pos--;
		str += trailingBytesForUTF8[c] + 1;
	}
	return str - str_save;
}

/*****************************************************************************/

int utf8charpos(const utf8 *str, int pos)
{
	int cp = 0;
	unsigned char c;

	while (pos &gt; 0 &amp;&amp; (c = *str))
	{
		str += trailingBytesForUTF8[c] + 1;
		pos -= trailingBytesForUTF8[c] + 1;
		cp++;
	}
	return cp;
}

/*****************************************************************************/

int utf8bytes(const utf8 *str)
{
	unsigned char c = *str;
	return trailingBytesForUTF8[c] + 1;
}

/*****************************************************************************/

utf8 *utf8ncpy(utf8 *to, const utf8 *from, int n)
{
	utf8 *saved_to = to;
	for (;n;n--)
	{
		unsigned char c = *from++;
		int len = trailingBytesForUTF8[c];

		*to++ = c;
		for (;len;len--)
		{
			*to++ = *from++;
		}
	}
	return saved_to;
}

/*****************************************************************************/

utf8 *utf8create(const void *from, const char *charset)
{
  /* utf8create_len() will stop on a null byte */
	return utf8create_len(from,charset,0x7fffffff);
}

/*****************************************************************************/

int utf8fromstr(const char *from, struct codeset *codeset, utf8 *dest, unsigned int dest_size)
{
	const char *src = from;
	unsigned char c;
	int conv = 0;

	if (dest_size &lt; 1)
		return 0;

	if (!codeset)
		codeset =  (struct codeset*)list_first(&amp;codesets_list);

	for (src = from;(c = (unsigned char)*src);src++)
	{
		unsigned char *utf8_seq;
		unsigned int l;

		utf8_seq = &amp;codeset-&gt;table[c].utf8[0];

		/* Recall that the first element represents
		 * the number of characters */
		l = utf8_seq[0];
		if (dest_size &lt;= l)
			break;

		utf8_seq++;
		for(;(c = *utf8_seq);utf8_seq++)
			*dest++ = c;

		dest_size -= l;
		conv++;
	}

	*dest = 0;
	return conv;
}

/*****************************************************************************/

utf8 *utf8create_len(const void *from, const char *charset, int from_len)
{
	int dest_size = 0;
	char *dest;
	char *src = (char*)from;
	unsigned char c;
	int len;
	struct codeset *codeset = codesets_find(charset);

	if (!from) return NULL;

	if (!codeset)
	{
		if (!mystricmp(charset,&quot;utf-7&quot;))
		{
			return (utf8*)utf7ntoutf8((char *)from,from_len);
		}
		if (!mystricmp(charset,&quot;utf-8&quot;))
		{
			return (utf8*)mystrdup((char *)from);
		}
		codeset = (struct codeset*)list_first(&amp;codesets_list);
	}

	len = from_len;

	while (((c = *src++) &amp;&amp; (len--)))
		dest_size += codeset-&gt;table[c].utf8[0];

	if ((dest = (char*)malloc(dest_size+1)))
	{
		char *dest_ptr = dest;

		for (src = (char*)from;from_len &amp;&amp; (c = *src);src++,from_len--)
		{
			unsigned char *utf8_seq;

			for(utf8_seq = &amp;codeset-&gt;table[c].utf8[1];(c = *utf8_seq);utf8_seq++)
				*dest_ptr++ = c;
		}

		*dest_ptr = 0;
		return (utf8*)dest;
	}
	return NULL;
}

/*****************************************************************************/

int utf8tostr(const utf8 *str, char *dest, unsigned int dest_size, struct codeset *codeset)
{
	unsigned int i;
	struct single_convert *f;
	char *dest_iter = dest;

	if (!dest_size)
	{
		return 0;
	}

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset || !str)
	{
		*dest = 0;
		return 0;
	}

	for (i=0;i &lt; dest_size-1;i++)
	{
		unsigned char c = *str;
		if (c)
		{
			if (c &gt; 127)
			{
				unsigned int len_add = trailingBytesForUTF8[c];
				unsigned int len_str = len_add + 1;

				BIN_SEARCH(codeset-&gt;table_sorted,0,255,mystrncmp((unsigned char*)str,codeset-&gt;table_sorted[m].utf8+1,len_str),f);

				if (f) *dest_iter++ = f-&gt;code;
				else *dest_iter++ = '_';

				str += len_add;
			} else *dest_iter++ = c;

			str++;
		} else break;
	}
	*dest_iter = 0;
	return i;
}

/*****************************************************************************/

char *utf8tostrcreate(const utf8 *str, struct codeset *codeset)
{
	char *dest;
	int len;
	if (!str) return NULL;
	len = strlen((char*)str);
	if ((dest = (char*)malloc(len+1)))
		utf8tostr(str,dest,len+1,codeset);
	return dest;
}

/*****************************************************************************/

int utf8tochar(const utf8 *str, unsigned int *chr, struct codeset *codeset)
{
	struct single_convert conv;
	struct single_convert *f;
	unsigned char c;
	int len = 0;

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset) return 0;

	if ((c = *str++))
	{
		int i;

		len = trailingBytesForUTF8[c];
		conv.utf8[1] = c;

		for (i=0;i&lt;len;i++)
		{
			if (!(conv.utf8[i+2] = *str++))
			{
				/* We encountered a 0 byte although the trailing byte suggested
				 * a different length. Hence the given utf8 sequence is not
				 * considered as valid */
				*chr = 0;
				return i+1;
			}
		}
		conv.utf8[2+len] = 0;

		if ((f = (struct single_convert*)bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode)))
		{
			*chr = f-&gt;code;
		} else *chr = 0;
	} else *chr = 0;
	return len+1;
}

/*****************************************************************************/

static inline int utf8cmp_single(unsigned char *a, unsigned char *b)
{
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
	int d;

	if ((d = a[0] - b[0])) return d;
	if ((d = a[1] - b[1])) return d;
	if ((d = a[2] - b[2])) return d;
	if ((d = a[3] - b[3])) return d;
	return 0;
#else
	return (*((unsigned int *)a) - *((unsigned int *)b));
#endif
}

/*****************************************************************************/

int utf8tolower(const char *str, char *dest)
{
	unsigned char ch[4] = {0,0,0,0};
	unsigned char c;
	struct uniconv *uc;
	int bytes;
	int i;

	c = *str++;
	if (c&lt;0x80)
	{
		*dest = tolower(c);
		return 1;
	}
	bytes = trailingBytesForUTF8[c];
	if (bytes &gt; 3)
	{
		*dest++ = c;
		memcpy(dest + 1,str + 1,bytes);
		return bytes + 1;
	}

	ch[3-bytes] = c;
	for (i=bytes-1;i&gt;=0;i--)
	{
		if (!(ch[3-i] = *str++))
			return 0;
	}

	BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),utf8cmp_single(utf8_tolower_table[m].from, ch),uc);

	if (uc)
		memcpy(dest, uc-&gt;to + 3 - bytes, bytes + 1);
	else
		memcpy(dest, ch + 3 - bytes, bytes + 1);
	return bytes + 1;
}

/*****************************************************************************/

int utf8stricmp(const char *str1, const char *str2)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (1)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8stricmp_len(const char *str1, const char *str2, int len)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (len&gt;0)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;
		len--;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;

				len--;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8match(const char *haystack, const char *needle, int case_insensitive, match_mask_t *match_mask)
{
	int h, n;
	int needle_len;
	int haystack_len;

	unsigned char hc;
	unsigned char nc;

	haystack_len = strlen(haystack);
	needle_len = strlen(needle);

	h = 0;
	n = 0;
	while (h &lt; haystack_len &amp;&amp; n &lt; needle_len)
	{
		int match;
		int hbytes;
		int nbytes;

		match = 0;
		hc = haystack[h];
		nc = needle[n];

		hbytes = trailingBytesForUTF8[hc];
		nbytes = trailingBytesForUTF8[nc];

		if (hbytes == nbytes)
		{
			if (hc == nc)
			{
				int i;

				match = 1;

				for (i=0; i &lt; hbytes; i++)
				{
					if (haystack[i+1] != needle[i+1])
						match = 0;
				}
			} else
			{
				if (hbytes == 0 &amp;&amp; case_insensitive)
				{
					if (tolower(hc) == tolower(nc))
					{
						match = 1;
					}
				}
			}

			if (!match &amp;&amp; case_insensitive &amp;&amp; hbytes &gt; 0)
			{
				char hchars[6] = {0};
				char nchars[6] = {0};
				int hl, nl;

				if ((hl = utf8tolower(&amp;haystack[h], hchars)) &gt; 0 &amp;&amp;
					(nl = utf8tolower(&amp;needle[n], nchars)) &gt; 0)
				{
					if (hl == nl)
					{
						match = memcmp(hchars, nchars, nl) == 0;
					}
				}

			}
		}

		if (match)
		{
			n += nbytes + 1;
		}

		if (match_mask)
		{
			unsigned int match_pos;

			match_pos = match_bitmask_pos(h);
			if (match)
			{
				match_mask[match_pos] |= match_bitmask(h);
			} else
			{
				match_mask[match_pos] &amp;= ~match_bitmask(h);
			}
		}

		h += hbytes + 1;
	}

	if (n == needle_len)
	{
		if (match_mask)
		{
			/* Make sure that the remaining relevant positions are cleared */
			for (;h &lt; haystack_len; h++)
			{
				match_mask[match_bitmask_pos(h)] &amp;= ~match_bitmask(h);
			}
		}
		return 1;
	}
	return 0;
}

/*****************************************************************************/

char *utf8stristr(const char *str1, const char *str2)
{
	int str2_len;

	if (!str1 || !str2) return NULL;

	str2_len = strlen(str2);

	while (*str1)
	{
		if (!utf8stricmp_len(str1,str2,str2_len))
			return (char*)str1;
		str1++;
	}
	return NULL;
}

/*****************************************************************************/

const char *uft8toucs(const char *chr, unsigned int *code)
{
	unsigned char c = *chr++;
	unsigned int ucs = 0;
	int i,bytes;
	if (!(c &amp; 0x80))
	{
		*code = c;
		return chr;
	} else
	{
		if (!(c &amp; 0x20))
		{
			bytes = 2;
			ucs = c &amp; 0x1f;
		}
		else if (!(c &amp; 0x10))
		{
			bytes = 3;
			ucs = c &amp; 0xf;
		}
		else if (!(c &amp; 0x08))
		{
			bytes = 4;
			ucs = c &amp; 0x7;
		}
		else if (!(c &amp; 0x04))
		{
			bytes = 5;
			ucs = c &amp; 0x3;
		}
		else /* if (!(c &amp; 0x02)) */
		{
			bytes = 6;
			ucs = c &amp; 0x1;
		}

		for (i=1;i&lt;bytes;i++)
			ucs = (ucs &lt;&lt; 6) | ((*chr++)&amp;0x3f);
	}
	*code = ucs;
	return chr;
}

static unsigned char base64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/&quot;;
static short invbase64[128];

static unsigned char ibase64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,&quot;;
static short iinvbase64[128];

static unsigned char direct[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'(),-./:?&quot;;
static unsigned char optional[] = &quot;!\&quot;#$%&amp;*;&lt;=&gt;@[]^_`{|}&quot;;
static unsigned char spaces[] = &quot; \011\015\012&quot;;		/* space, tab, return, line feed */
static char mustshiftsafe[128];
static char mustshiftopt[128];

static int needtables = 1;

static void tabinit(void)
{
	int i, limit;

	for (i = 0; i &lt; 128; ++i)
	{
		mustshiftopt[i] = mustshiftsafe[i] = 1;
		invbase64[i] = -1;
	}
	limit = strlen((char*)direct);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[direct[i]] = mustshiftsafe[direct[i]] = 0;
	limit = strlen((char*)spaces);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[spaces[i]] = mustshiftsafe[spaces[i]] = 0;
	limit = strlen((char*)optional);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[optional[i]] = 0;
	limit = strlen((char*)base64);
	for (i = 0; i &lt; limit; ++i)
		invbase64[base64[i]] = i;

	/* that's for the modified imap utf7 stuff */
	limit = strlen((char*)ibase64);
	for (i = 0; i &lt; limit; ++i)
		iinvbase64[ibase64[i]] = i;

	needtables = 0;
}

#if __cplusplus &gt;= 201703L
#define DECLARE_BIT_BUFFER unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#else
#define DECLARE_BIT_BUFFER register unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#endif

#define BITS_IN_BUFFER bufferbits
#define WRITE_N_BITS(x, n) ((BITbuffer |= ( ((x) &amp; ~(-1L&lt;&lt;(n))) &lt;&lt; (32-(n)-bufferbits) ) ), bufferbits += (n) )
#define READ_N_BITS(n) ((buffertemp = (BITbuffer &gt;&gt; (32-(n)))), (BITbuffer &lt;&lt;= (n)), (bufferbits -= (n)), buffertemp)

/*****************************************************************************/

char *utf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '+' || c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('+',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '+')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8toiutf7(char *utf8, int sourcelen)
{
	FILE *fh;
	char *dest = NULL;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;
		int shifted = 0;
		DECLARE_BIT_BUFFER;

		while (1)
		{
			unsigned char c;
			int noshift;

			if (sourcelen)
			{
				c = *utf8;
				noshift = (c &gt;= 0x20 &amp;&amp; c &lt;= 0x7e) &amp;&amp; (c != '&amp;');
			} else
			{
				c = 0;
				noshift = 1;
			}

			if (shifted)
			{
				while (BITS_IN_BUFFER &gt;= 6)
				{
					unsigned char bits = READ_N_BITS(6);
					fputc(ibase64[bits],fh);
				}

				if (noshift)
				{
					int bits_in_buf = BITS_IN_BUFFER;

					if (bits_in_buf)
					{
						unsigned char bits = READ_N_BITS(bits_in_buf);
						bits &lt;&lt;= 6 - bits_in_buf;
						fputc(ibase64[bits],fh);
					}
					shifted = 0;
					fputc('-',fh);
				}
			}

			if (!c) break;

			if (noshift)
			{
				if (c == '&amp;')
				{
					fputs(&quot;&amp;-&quot;,fh);
				} else fputc(c,fh);
				utf8++;
				sourcelen--;
			} else
			{
				UTF8 *source = (UTF8*)utf8;
				UTF16 dest = 0;
				UTF16 *dest_ptr = &amp;dest;
				ConversionResult res;

				res = ConvertUTF8toUTF16(&amp;source, source + sourcelen, &amp;dest_ptr, dest_ptr + 1, strictConversion);
				if (res == conversionOK || res == targetExhausted)
				{
					sourcelen -= trailingBytesForUTF8[c] + 1;
					utf8 += trailingBytesForUTF8[c] + 1;

					if (!shifted)
					{
						fputc('&amp;',fh);
						shifted = 1;
					}

					WRITE_N_BITS(dest,16);
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}
	return dest;
}

/*****************************************************************************/

char *iutf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('&amp;',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '&amp;')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8topunycode(const utf8 *source, int sourcelen)
{
	enum punycode_status status;
	const utf8 *sourceend;
	char *puny;
	punycode_uint puny_len;

	punycode_uint *dest, *target;
	punycode_uint dest_len;

	if (!(dest = (punycode_uint *)malloc(sourcelen * sizeof(punycode_uint))))
		return NULL;

	target = dest;
	sourceend = source + sourcelen;

	while (source &lt; sourceend)
	{
		punycode_uint ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*(UTF8*)source];

		if (source + extraBytesToRead &gt;= sourceend)
		{
			/* source exhausted */
			free(dest);
			return NULL;
		}

		/* Do this check whether lenient or strict */
		if (!isLegalUTF8((UTF8*)source, extraBytesToRead+1))
		{
			free(dest);
			return NULL;
		}

		/*
		 * The cases all fall through.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		}
	}

	dest_len = target - dest; /* No 0 ending */
	puny_len = dest_len * 2;

	do
	{
		int strored_puny_len = puny_len;

		if (!(puny = (char*)malloc(puny_len+5)))
		{
			free(dest);
			return NULL;
		}
		status = punycode_encode(dest_len, dest, NULL /* case flags */, &amp;puny_len, puny);

		if (status == punycode_success)
		{
			puny[puny_len] = 0;
			free(dest);
			return puny;
		}
		puny_len = strored_puny_len * 2;
	} while (status == punycode_big_output);

	free(puny);
	free(dest);
	return NULL;
}
/*****************************************************************************/

utf8 *punycodetoutf8(const char *source, int sourcelen)
{
	enum punycode_status status;
	punycode_uint *utf32;
	punycode_uint length;

	length = sourcelen;

	if (!(utf32 = (punycode_uint*)malloc(sizeof(punycode_uint)*sourcelen)))
		return NULL;

	status = punycode_decode(sourcelen, source, &amp;length, utf32, NULL);
	if (status == punycode_success)
	{
		utf8 *dest = (utf8*)malloc(sourcelen * 4);
		if (dest)
		{
			UTF8 *dest_start = (UTF8*)dest;
			UTF32 *source_start = (UTF32*)utf32;

			ConvertUTF32toUTF8((UTF32**)&amp;source_start, (UTF32*)(utf32) + length, &amp;dest_start, dest_start + sourcelen * 4 - 2, strictConversion);
			*dest_start = 0;
			free(utf32);
			return dest;
		}
	}
	free(utf32);
	return NULL;
}

/*****************************************************************************/

int isascii7(const char *str)
{
	char c;
	if (!str) return 1;
	while ((c = *str++))
	{
		if (c &amp; 0x80) return 0;
	}
	return 1;
}
&lt;/syntaxhighlight&gt;

[https://github.com/jens-maus/yam YAM] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

[https://github.com/sacredbanana/AmigaGPT AmigaGPT]

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


From Wookiechat

Charsets: wookiechat doesnt need the incoming charset to be configured exactly anymore. When someone types weird characters, wookie will scan it for utf8 characters.. if it has those, then it'll convert it to ascii as best an Amiga can using codesets.library. if theres none, then it'll just use codesets.library Codesets_FindBest() function.

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


== Library Calls ==

&lt;pre&gt;
TABLE OF CONTENTS

codesets.library/codesets.library
codesets.library/CodesetsSupportedA
codesets.library/CodesetsFindA
codesets.library/CodesetsFindBestA
codesets.library/CodesetsConvertStrA
codesets.library/CodesetsFreeA
codesets.library/CodesetsFreeVecPooledA
codesets.library/CodesetsSetDefaultA
codesets.library/CodesetsListCreateA
codesets.library/CodesetsListDeleteA
codesets.library/CodesetsListAddA
codesets.library/CodesetsListRemoveA
codesets.library/CodesetsUTF8CreateA
codesets.library/CodesetsUTF8ToStrA
codesets.library/CodesetsUTF8Len
codesets.library/CodesetsIsValidUTF8
codesets.library/CodesetsIsLegalUTF8
codesets.library/CodesetsIsLegalUTF8Sequence
codesets.library/CodesetsStrLenA
codesets.library/CodesetsConvertUTF16toUTF32
codesets.library/CodesetsConvertUTF16toUTF8
codesets.library/CodesetsConvertUTF32toUTF16
codesets.library/CodesetsConvertUTF32toUTF8
codesets.library/CodesetsConvertUTF8toUTF16
codesets.library/CodesetsConvertUTF8toUTF32
codesets.library/CodesetsDecodeB64A
codesets.library/CodesetsEncodeB64A


codesets.library/codesets.library

    *******************************************************************
    Copyright (c) 2005-2008 by codesets.library Open Source Team
    $Id$
    $URL$

    codesets.library is an AmigaOS shared library which provides
    functions to deal with different kind of codesets. It provides
    general character conversion routines, e.g. for converting
    from one charset (e.g. UTF8) into another (e.g. ISO-8859-1) or
    vice versa.

    codesets.library is mainly based on some code from UNICODE, some
    code from the SimpleMail project as well as some additions done
    by the codesets.library Open Source Team.

    It is released and distributed under the terms of the GNU Lesser
    General Public License (LGPL) and available free of charge.

    Please visit http://www.sf.net/projects/codesetslib/ for
    the very latest version and information regarding codesets.library.
    *******************************************************************

    For some short introduction on how to use codesets.library, the
    following pharagraph should provide a good summary. What you
    usually want to do with codesets.library is, to convert strings from
    one so-called &quot;Source Codeset&quot; into another &quot;Destination Codeset&quot;.
    The following list are only the main functions provided to
    developers, wanting to achieve this conversion in their applications:


    CodesetsSupportedA()
    --------------------

      For querying codesets library which codesets/charsets it supports
      either by its internal available charsets or by having obtained
      them from the operating system (e.g. AmigaOS4), this function
      can be used.

      E.g. in a MUI application you would do something like:

      -- cut here --
      STRPTR *array;

      if((array = CodesetsSupportedA(NULL)))
      {
        DoMethod(list, MUIM_List_Insert, array, -1, MUIV_List_Insert_Sorted);
        CodesetsFreeA(array, NULL);
      }
      -- cut here --


    CodesetsFindA()
    ---------------

      For processing/converting a specific string, you normally have to
      specify in which codeset this string has to be intepreted. For this
      purpose you have to pass a so-called &quot;Source Codeset&quot; to the main
      function of codesets.library. With the &quot;CodesetsFindA()&quot; function you
      can query codesets.library for providing you a pointer to the
      corresponding codeset structure which you afterwards will forward to
      the main conversion routines later on.

      For receiving the pointer to the Amiga-1251 codeset:
      -- cut here --
      struct codeset *cs;

      if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                            CSA_FallbackToDefault, FALSE,
                            TAG_DONE)))
      {
        ...
      }
      -- cut here --

      For querying codesets.library for the currently used system wide
      default of your running operating system:
      -- cut here --
      struct codeset *default;

      if((default = CodesetsFindA(NULL, NULL)))
      {
        ...
      }
      -- cut here --


    CodesetsConvertStrA()
    ---------------------

      The more or less most common function to use in codesets.library is
      definitly this function. It allows to convert a string from
      one &quot;Source Codeset&quot; to another &quot;Destination Codeset&quot;. It takes
      the source string converts it internally into UTF8 if necessary and
      then directly convert the UTF8 to the specified destination codeset.

      To convert a string 'str' to a destination codeset:
      -- cut here --
      STRPTR destString;

      if((destString = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                          CSA_DestCodeset,   destCodeset,
                                          CSA_Source,        str,
                                          TAG_DONE)))
      {
        ....

        CodesetsFreeA(destString, NULL);
      }
      -- cut here --

   Even if the above functions should cover most of the common functionality
   an ordinary user of codesets.library would require, it supplies a lot more
   functions which in fact we will not go into detail here but present
   certain examples in the respective documentation section of each function.

   However, if you find the documentation is still too limited or you feel
   some major functionality is missing regarding dealing with codesets,
   please let us know so that we or even you can improve it.


   Your codesets.library Open Source Team.
   February 2006


codesets.library/CodesetsSupportedA

   NAME
    CodesetsSupportedA - returns names of supported codesets

   SYNOPSIS
    array = CodesetsSupportedA(attrs);
                               A0

    STRPTR * CodesetsSupportedA(struct TagItem *);

    array = CodesetsSupported(tag1, ...);
                              A0

    STRPTR * CodesetsSupported(Tag, ...);

   FUNCTION
    Returns a NULL terminated array of the supported codeset
    names. The array _must_ be freed with CodesetsFreeA().

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

     CSA_AllowMultibyteCodesets (BOOL)
       Include multibyte codesets (UTF8, UTF16, UTF32) in the
       generated names array.
       Default: TRUE

   RESULT
    array - the names array or NULL on an error.

   EXAMPLE
    For printing out all supported codeset names:

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      int i;

      for(i=0; array[i] != NULL; i++)
        printf(&quot;%s&quot;, array[i]);

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindA

   NAME
    CodesetsFindA - finds a codeset

   SYNOPSIS
    codeset = CodesetsFindA(name, attrs);
    D0                      A0    A1

    struct codeset * CodesetsFindA(STRPTR, struct TagItem *);

    codeset = CodesetsFind(name, tag1, ...);
    D0                     A0    A1

    struct codeset * CodesetsFind(STRPTR, Tag, ...);

   FUNCTION
    Finds and returns a codeset by its name. The data behind the
    pointer should be considered read-only and must not be altered
    in any way.

   INPUTS
    name - the codeset name (or alias) to find
    attrs - a list of additional tag items. Valid items are:

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied codeset name can't be found.
        Default: TRUE

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

   RESULT
    codeset - the codeset or NULL on an error

   EXAMPLE
     E.g. for receiving the pointer to the Amiga-1251 codeset:

     -- cut here --
     struct codeset *cs;

     if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                           CSA_FallbackToDefault, FALSE,
                           TAG_DONE)))
     {
       ...
     }
     -- cut here --

     For querying codesets.library for the currently used system
     wide default of your running operating system:
     -- cut here --
     struct codeset *default;

     if((default = CodesetsFindA(NULL, NULL)))
     {
       ...
     }
     -- cut here --

   NOTE
    Please note for querying the system's default codeset the
    method of finding this codeset is highly dependent on the way
    the operating system can be queried for it. E.g. on AmigaOS4
    the default codeset is queried with updated system functions,
    but for AmigaOS3 a static list of language&lt;&gt;codeset mappings
    is used.

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindBestA

   NAME
    CodesetsFindBestA - finds the best codeset matching a
                        string content.

   SYNOPSIS
    codeset = CodesetsFindBestA(attrs);
    D0                          A0

    struct codeset * CodesetsFindBestA(struct TagItem *);

    codeset = CodesetsFindBest(tag1, ...);
    D0                         A0

    struct codeset * CodesetsFindBest(Tag, ...);

   FUNCTION
    Returns the best found codeset for the given text in the supplied
    codeset family. In case no proper codeset for the supplied source string
    could be found, NULL is returned or the default codeset if the
    CSA_FallbackToDefault attribute is set to TRUE. In addition, in case
    the CSA_ErrPtr is given, the amount of failed identifications (chars)
    are returned.

   INPUTS
    attrs - a list of tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to check just a part
        Default: string length of CSA_Source

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found errors (not identifyable chars)
        Default: NULL

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

      CSA_CodesetFamily (ULONG)
        To narrow the analyze, a user might define the codeset family
        of which the supplied text might be composed of. The reason for
        this is, that there isn't a unique identification algorithm
        which can tell the codeset out of a given text. So to narrow
        the identification, the follow values might be specified:

          CSV_CodesetFamily_Latin    - Latin codeset family (e.g. ISO-8859-X)
          CSV_CodesetFamily_Cyrillic - Cyrillic codeset family (e.g. KOI8R)

        Default: CSV_CodesetFamily_Latin

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied text couldn't be identified
        Default: FALSE

   RESULT
    codeset - the best matching codeset or NULL in case a NULL pointer
              was supplied as the source string.

   EXAMPLE
     E.g. for receiving the pointer to 'best matching' codeset matching
     a KOI8-R string:

     -- cut here --
     struct codeset *cs;
     char str[] = &quot;îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;;
     int errPtr;

     if((cs = CodesetsFindBest(CSA_Source, str,
                               CSA_ErrPtr, &amp;errPtr,
                               CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                               CSA_FallBackToDefault, FALSE,
                               TAG_DONE)))
     {
       ... should return the KOI8-R codeset ...
     }
     -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsConvertStrA

   NAME
    CodesetsConvertStrA - converts a string from one source codeset to
                          another destination codeset.

   SYNOPSIS
    dest = CodesetsConvertStrA(attrs)
    D0                         A0

    STRPTR CodesetsConvertStrA(struct TagItem *);

    dest = CodesetsConvertStr(tag1, ...);
    D0                        A0

    STRPTR CodesetsConvertStr(Tag, ...);

   FUNCTION
    The function takes source string which is encoded in a so-called
    'Source codeset' and converts it immediately into an equivalent
    string which will be encoded in the corresponding 'Destination Codeset'.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_DestCodeset (struct codeset *)
        The codeset to which the source string should be converted to.
        Default: the system's default codeset

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string
        which is returned.

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    either a pointer to the generated destination string or NULL
    on a found error.

   EXAMPLE
    To convert an ISO-8859-1 encoded string 'src' into an Amiga-1251
    equivalent 'dst' string:
    -- cut here --
    STRPTR src, dst;
    struct codeset *srcCodeset, *dstCodeset;

    srcCodeset = CodesetsFindA(&quot;ISO-8859-1&quot;, NULL);
    dstCodeset = CodesetsFindA(&quot;Amiga-1251&quot;, NULL);

    if((dst = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                 CSA_DestCodeset,   dstCodeset,
                                 CSA_Source,        src,
                                 TAG_DONE)))
    {
      ....

      CodesetsFreeA(dst, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsFreeA


codesets.library/CodesetsFreeA

   NAME
    CodesetsFreeA - frees objects previously internally allocated
                    by codesets.library

   SYNOPSIS
    CodesetsFreeA(obj, attrs)
                  A0   A1
    void CodesetsFreeA(APTR, struct TagItem *);

    CodesetsFree(obj, tag1, ...);
                 A0   A1
    void CodesetsFree(APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library. E.g. using
    functions like CodesetsSupportedA() or CodesetsConvertStrA().

   INPUTS
    obj - the object to free
    attrs - a list of additional tag items. Currently non items.

   RESULT
    no result

   EXAMPLE

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      ...

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsSupportedA
    codesets.library/CodesetsConvertStrA


codesets.library/CodesetsFreeVecPooledA

   NAME
    CodesetsFreeVecPooledA - frees objects previously allocated
                             by methods supporting CSA_Pool

   SYNOPSIS
    CodesetsFreeVecPooledA(pool, obj, attrs)
                           A0    A1   A2
    void CodesetsFreeVecPooledA(APTR, APTR, struct TagItem *);

    CodesetsFreeVecPooled(pool, obj, tag1, ...);
                          A0    A1   A2
    void CodesetsFreeVecPooled(APTR, APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library via a
    private memory pool which was previously used on codesets
    functions via the CSA_Pool tag.

   INPUTS
    pool - pointer to the private memory pool
    obj - the object to free
    attrs - a list of additional tag items. Valid tags are:

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    no result

   EXAMPLE

    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsSetDefaultA

   NAME
    CodesetsSetDefaultA - sets the default codeset, overwriting
                          the system default if necessary.

   SYNOPSIS
    codeset = CodesetsSetDefaultA(name, attrs);
                                  A0    A1

    struct codeset * CodesetsSetDefaultA(STRPTR, struct TagItem *);

    codeset = CodesetsSetDefault(name, tag1, ...);
                                 A0    A1

    struct codeset * CodesetsSetDefault(STRPTR, Tag, ...);

   FUNCTION
    Sets the default codeset to name. The codeset will be stored in
    the environment variable 'codeset_default'.

   INPUTS
    name - the name of the codeset to set as default
    attrs - a list of additional tag items. Valid items are:

      CSA_Save (BOOL)
        If TRUE the codeset will be permanently saved and survives
        a reset. Otherwise the default setting will just last until
        the next reboot.
        Default: FALSE

   RESULT
    codeset - the codeset or NULL

   NOTE
    In case the operating system supports the direct query of the
    currently active system's default codeset, this function will
    still overwrite this setting. So by using this method a user may
    overwrite all system's setting and set a global default codeset
    for his machine no matter what the OS suggests. However, in case
    your operating sytsem perfectly supports the querying of the
    system's default codeset (e.g. AmigaOS4) you are adviced to use
    this function with care - or even avoid to use it at all.

   SEE ALSO
    codesets.library/CodesetsFindA


codesets.library/CodesetsListCreateA

   NAME
    CodesetsListCreateA - creates a private, task-wise codeset list
                          and returns it to the user for further reference.

   SYNOPSIS
    list = CodesetsListCreateA(attrs);
    D0                         A0

    struct codesetList * CodesetsListCreateA(struct TagItem *);

    list = CodesetsListCreate(tag1, ...);
    D0                        A0

    struct codesetList * CodesetsListCreateA(Tag, ...);

   FUNCTION
    This function allows to create a private, task-wise codeset list by
    loading charset files from either a whole directory tree, a specific
    charset file or even by using an existing codeset structure.
    By using this function, an application might load and carry its very
    own private charsets in parallel to the internal charsets of
    codeset.library. This way each application can provide a different
    codeset list to the user without having to load and manage these
    lists on their own.

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    list - the private codeset list or NULL on an error condition

   NOTE
    For convienence, if no tag item attribute at all is supplied to the
    function, codesets.library will try to load charsets from the
    corresponding &quot;PROGDIR:Charsets&quot; directoy and add found codeset to
    the list. However, in case a tag item is specified (no matter what
    kind) the PROGDIR: scanning will be omitted.

   EXAMPLE
    For loading all found charset files from PROGDIR:Charsets:

    -- cut here --
    struct codesetList *csList;

    if((csList = CodesetsListCreateA(NULL)))
    {
      STRPTR codesetArray = CodesetsSupported(CSA_CodesetList, csList,
                                              TAG_DONE);

      // codesetsArray should now also carry our private
      // codesets from PROGDIR:Charsets
      ...

      CodesetsListDeleteA(CSA_CodesetList, csList,
                          TAG_DONE);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA
    codesets.library/CodesetsListSupportedA
    codesets.library/CodesetsListFindA
    codesets.library/CodesetsListFindBestA


codesets.library/CodesetsListDeleteA

   NAME
    CodesetsListDeleteA - deletes/frees all resources of previously created
                          private codeset lists.

   SYNOPSIS
    result = CodesetsListDeleteA(attrs);
    D0                           A0

    BOOL CodesetsListDeleteA(struct TagItem *);

    result = CodesetsListDelete(tag1, ...);
    D0                          A0

    BOOL CodesetsListDelete(Tag, ...);

   FUNCTION
    This function deletes all resources (also the contained codeset
    structures per default) and frees the memory of previously allocated
    private codeset lists.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        Pointer to a previously created, private codeset list whos
        resources should be freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all contained codesets should also be freed/deleted,
        otherwise just frees the list object itself.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Please note that if you added an explicit codeset structure to more
    than two private codeset lists you may run into problems with you
    don't take care of this yourself. This is a dumb function which just
    walks through the list and frees all resources. Set CSA_FreeCodesets
    to FALSE in case you just want to free the list object.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA


codesets.library/CodesetsListAddA

   NAME
    CodesetsListAddA - allows to add additional codesets to an already
                       existing private codeset list previously created with
                       CodesetsListCreateA().

   SYNOPSIS
    result = CodesetsListAddA(attrs);
    D0                        A0

    BOOL CodesetsListAddA(struct TagItem *);

    result = CodesetsListAdd(tag1, ...);
    D0                       A0

    BOOL CodesetsListAdd(Tag, ...);

   FUNCTION
    This function allows to add additional codesets to an already existing
    private codeset list. Either codesets themself may be added directly, or
    the path to either a file or a directory may be specified from which
    additional codesets may be loaded from known charset files.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Be careful when adding one codeset to more than one codeset list as
    you may run into problems when freeing the list afterwards.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsListRemoveA

   NAME
    CodesetsListRemoveA - removes a single or multiple codesets from a
                          previously created codeset list.

   SYNOPSIS
    result = CodesetsListRemoveA(attrs);
    D0                           A0

    BOOL CodesetsListRemoveA(struct TagItem *);

    result = CodesetsListRemove(tag1, ...);
    D0                          A0

    BOOL CodesetsListRemove(Tag, ...);

   FUNCTION
    This function allows to remove single or multiple codesets from a
    previously created codeset list. The removed codeset structures will
    also be freed/deleted per default.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        Pointer to a codeset structure which should be removed from
        its corresponding list. Per default its resources will also
        be internally freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all supplied codesets should also be freed/deleted,
        otherwise the codesets will just be removed from their lists.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    The function will automatically prevent removal of codesets from the
    internal codeset list of codesets.library and will return FALSE in
    case a user tried to remove a codeset from the internal list.

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsUTF8CreateA

   NAME
    CodesetsUTF8CreateA - creates an UTF8 compliant string
                          interpretation out of a supplied source
                          string.


   SYNOPSIS
    utf8 = CodesetsUTF8CreateA(attrs);
                               A0
    UTF8 * CodesetsUTF8CreateA(struct TagItem *);

    utf8 = CodesetsUTF8Create(tag1, ...);
                              A0
    UTF8 * CodesetsUTF8Create(Tag, ...);


   FUNCTION
    Creates an UTF8 from a string which is encoded in specified
    codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole utf8. If CSA_Dest can't
        contain the utf8, a brand new buffer is allocated. If
        CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the utf8 string

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the UTF8 a new buffer is allocated
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, utf8, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(utf8, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    utf8 - the utf8 string or NULL
           If CSA_DestHook is used always NULL.
           If CSA_DestHook is not used NULL means failure
           to allocate mem.

   EXAMPLE
    The shortest invocation is:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    In case you want to use your pool to allocate mem:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If your pool is to be arbitrated via a semaphore:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;
    struct SignalSemaphore *sem;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  CSA_PoolSem,    sem,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If you want to use your own buffer to reduce mem
    allocation:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[256];

    if((utf8 = CodesetsUTF8Create(CSA_Source,  str,
                                  CSA_Dest,    buf,
                                  CSA_DestLen, sizeof(buf),
                                  TAG_DONE)))
    {
        ...

        if(utf8 != buf)
          CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    If your string are max MAXLEN chars long (e.g. image to be
    in a MUI application and you know the max size of your
    string gadgets), you should better supply your own buffer:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[MAXSIZE*6+1];

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  CSA_Dest,   buf,
                                  CSA_Dest,   sizeof(buf),
                                  TAG_DONE)))
    {
        ...
    }
    -- cut here --


    If you strings are very large and so you are sure there is
    no mem for them and or you have your own reasons to do
    that:
    -- cut here --
    static ULONG ASM SAVEDS
    destFun(REG(a0, struct Hook *hook),
            REG(a2, struct convertMsg *msg),
            REG(a1, STRPTR buf))
    {
      printf(&quot;[%3ld] [%s]\n&quot;,msg-&gt;len,buf);
      if(msg-&gt;state == CSV_End)
        printf(&quot;\n&quot;);

      return 0;
    }

    struct Hook dest;
    dest.h_Entry = (HOOKFUNC)destFun;

    CodesetsUTF8Create(CSA_Source,    str,
                       CSA_DestHook,  &amp;dest,
                       TAG_DONE);
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8ToStrA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8ToStrA

   NAME
    CodesetsUTF8ToStrA - converts an UTF8 encoded string into
                         a specified destination codeset.


   SYNOPSIS
    str = CodesetsUTF8ToStrA(attrs);
    D0                       A0

    STRPTR CodesetsUTF8ToStrA(attrs);

    str = CodesetsUTF8ToStr(tag1, ...);
    D0                      A0

    STRPTR CodesetsUTF8ToStr(Tag,...);


   FUNCTION
    Convert an utf8 string to a specified codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source. Must be &gt; 0 or the function returns
        NULL.
        Default: string length of CSA_Source - strlen()

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole converted string. If CSA_Dest
        can't contain the output string, a brand new buffer is allocated.
        If CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestCodeset (struct codeset *)
        The codeset to which the UTF8 string should be encoded to.
        Default: the system's default codeset

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string.

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the output string, a new buffer is allocated.
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, string, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(string, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found issues (number of not convertable chars)
        Default: NULL

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    str - the string or NULL
          If CSA_DestHook is used always NULL.
          If CSA_DestHook is not used NULL means failure
          to allocate mem.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8Len

   NAME
    CodesetsUTF8Len - returns the length of a supplied utf8 string.

   SYNOPSIS
    len = CodesetsUTF8Len(utf8);
    D0                    A0

    ULONG CodesetsUTF8Len(UTF8 *);

   FUNCTION
    Returns the amount of real characters stored in a supplied UTF8
    string. This is _NOT_ the space required to store the UTF8 string,
    it is the actual number of _real_ character the UTF8 represents.

   INPUTS
    utf8 - pointer to the UTF8 string generated by the internal
           functions of codesets.library

   RESULT
    len - length of utf8

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsValidUTF8

   NAME
    CodesetsIsValidUTF8 - tells if a supplied standard string is meant to
                          carry a perfectly valid UTF8 sequence

   SYNOPSIS
    result = CodesetsIsValidUTF8(str);
    D0                           A0

    BOOL CodesetsIsValidUTF8(STRPTR);

   FUNCTION
    Returns TRUE in case the supplied string only contains char sequences
    which are compatible to the UTF8 standard.

   INPUTS
    str - a standard STRPTR string.

   RESULT
    result - TRUE in case the string conatins valid UTF8 data.

   NOTE
    This function uses the common 'GOOD_UCS' macro together with parsing
    the whole string. This means that it will only return TRUE in case
    the supplied string only contains UTF8 sequences. A mixture of UTF8
    and non-UTF8 sequences will result in the function returning FALSE.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8

   NAME
    CodesetsIsLegalUTF8 - check a UTF8 sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8(source, length);
                              A0      D0

    ULONG CodesetsIsLegalUTF8(UTF8 *, ULONG);


   FUNCTION
    Checks if source is a valid UTF8 sequence generated
    by the internal functions of codesets.library

   INPUTS
    source - the char sequence to check
    length - size of source

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8Sequence

   NAME
    CodesetsIsLegalUTF8Sequence - check a char sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8Sequence(source, end);
                                      A0      A1

    ULONG CodesetsIsLegalUTF8(UTF8 *, UTF8 *);

   FUNCTION
    Check if source is a valid UTF8 sequence within the
    source and end boundaries.

   INPUTS
    source - the char sequence to check
    end - pointer to the end of the sequence to check

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsStrLenA

   NAME
    CodesetsStrLenA - returns the length of the source string
                      in case it will be converted to an UTF8
                      string.

   SYNOPSIS
    len = CodesetsStrLenA(str, attrs)
                          A0   A1

    ULONG CodesetsStrLenA(STRPTR, struct TagItem *);

    len = CodesetsStrLen(str, tag1, ...);
                         A0   A1

    ULONG CodesetsStrLen(STRPTR, Tag, ...);

   FUNCTION
    Return the length (size) of str in case it will be converted to
    an UTF8 compliant string.

   INPUTS
    str - the string to obtain length of
    attrs - a list of additional tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        The codeset the source string is encoded in.
        Default: the system's default codeset

      CSA_SourceLen (ULONG)
        The length of str
        Default: string length of CSA_Source

   RESULT
    len - the length of the string if it will be converted to
          an UTF8 string.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA


codesets.library/CodesetsConvertUTF16toUTF32

   NAME
    CodesetsConvertUTF16toUTF32 - converts from UTF16 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF32(const UTF16 **,const UTF16 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF16toUTF8

   NAME
    CodesetsConvertUTF16toUTF8 - converts from UTF16 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF8(const UTF16 **,const UTF16 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF8.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF16

   NAME
    CodesetsConvertUTF32toUTF16 - converts from UTF32 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF16(const UTF32 **,const UTF32 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF8

   NAME
    CodesetsConvertUTF32toUTF8 - converts from UTF32 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF8(const UTF32 **,const UTF32 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF16

   NAME
    CodesetsConvertUTF8toUTF16 - converts from UTF8 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF16(const UTF8 **,const UTF8 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF32

   NAME
    CodesetsConvertUTF8toUTF32 - converts from UTF8 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF32(const UTF8 **,const UTF8 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsDecodeB64A

   NAME
    CodesetsDecodeB64A - decodes a supplied base64 encoded string
                         or file into plain text charwise.

   SYNOPSIS
    res = CodesetsDecodeB64A(attrs);
    D0                       A0

    ULONG CodesetsDecodeB64A(struct TagItem *);

    res = CodesetsDecodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsDecodeB64A(Tag, ....);

   FUNCTION
    Decodes a string or a complete base64 encoded file to a
    plain text buffer or also a destination file

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to decode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64FLG_NtCheckErr (BOOL)
        Don't stop on error.

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be still be encoded to.

   SEE ALSO
    codesets.library/CodesetsEncodeB64A


codesets.library/CodesetsEncodeB64A

   NAME
    CodesetsEncodeB64A - encodes a string or whole file
                         to base64

   SYNOPSIS
    res = CodesetsEncodeB64A(attrs);
    D0                       A0

    ULONG CodesetsEncodeB64A(struct TagItem *);

    res = CodesetsEncodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsEncodeB64(Tag, ....);

   FUNCTION
    Encodes the supplied string or file to either a whole
    buffer or also to a file.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to encode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString. Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64MaxLineLen (ULONG)
        Maximum length of encoded lines. 0&lt;v&lt;256
        Default: 72

      CSA_B64Unix (ULONG)
        If TRUE eol is \n (LF), otherwise \r\n (CRLF).
        Default: TRUE

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be encoded to.

   SEE ALSO
    codesets.library/CodesetsDecodeB64A

&lt;/pre&gt;</text>
      <sha1>m2rihzw4cvdpvu6y0e7cl05p9c6boo6</sha1>
    </revision>
    <revision>
      <id>4669774</id>
      <parentid>4669773</parentid>
      <timestamp>2026-09-12T17:10:02Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669774</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129429" sha1="fl9z373g352bf071ytv1qwqb9spkbo0" xml:space="preserve">{{ArosNav}}

==Introduction==

Character set (charsets) encoding is the process of assigning numbers to graphical characters, especially the written characters of human language

Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251      – Cyrillic (Amiga)
    ISO-8859-1      – Latin 1 aka Western European ASCII based 
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2      – Latin-2 aka Central/East European
    ISO-8859-3      – South European
    ISO-8859-4      – North European
    ISO-8859-5      – Slavic languages
    ISO-8859-9      – Turkish
    ISO-8859-15     – West European II
    ISO-8859-16     – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)

Windows-1252 was first character set in Windows. It was a copy of ASCII, but used 8-bits to represent 256 different characters (international letters). Windows-1252 is supported by all browsers.
&lt;/pre&gt;


[https://github.com/jens-maus/yam YAM] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

[https://github.com/sacredbanana/AmigaGPT AmigaGPT]

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


From Wookiechat

Charsets: wookiechat doesnt need the incoming charset to be configured exactly anymore. When someone types weird characters, wookie will scan it for utf8 characters.. if it has those, then it'll convert it to ascii as best an Amiga can using codesets.library. if theres none, then it'll just use codesets.library Codesets_FindBest() function.


==Source Code==

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;exec/libraries.h&gt;
#include &lt;libraries/codesets.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;proto/exec.h&gt;

#include &lt;stdio.h&gt;

/* This is just a very quickly written test, not a full-featured convertor */
#define BUF_SIZE 102400

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace *ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

struct codeset *srcCodeset;
struct codeset *destCodeset;

int main(int argc, char **argv)
{
  char *buf, *destbuf;
  ULONG destlen;
  FILE *f;

  if (argc &lt; 4)
  {
    fprintf(stderr, &quot;Usage: %s &lt;source codeset&gt; &lt;destination codeset&gt; &lt;source file&gt;\n&quot;, argv[0]);
    return 0;
  }
  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
     GETINTERFACE(ICodesets, CodesetsBase))
  {
    srcCodeset = CodesetsFind(argv[1], CSA_FallbackToDefault, FALSE, TAG_DONE);
    if (srcCodeset)
    {
      destCodeset = CodesetsFind(argv[2], CSA_FallbackToDefault, FALSE, TAG_DONE);
      if (destCodeset)
      {
        buf = AllocMem(BUF_SIZE, MEMF_CLEAR);

        if (buf)
        {
          f = fopen(argv[3], &quot;r&quot;);
          if (f)
          {
            fread(buf, BUF_SIZE-1, 1, f);
            fclose(f);
            destbuf = CodesetsConvertStr(CSA_SourceCodeset, (IPTR)srcCodeset,
                                         CSA_DestCodeset, (IPTR)destCodeset,
                                         CSA_Source, (IPTR)buf,
                                         CSA_DestLenPtr, (IPTR)&amp;destlen,
                                         TAG_DONE);
            if (destbuf)
            {
              fprintf(stderr, &quot;Result length: %u\n&quot;, (unsigned int)destlen);
              fwrite(destbuf, destlen, 1, stdout);
              fputc('\n', stderr);
              CodesetsFreeA(destbuf, NULL);
            }
          else
            fprintf(stderr, &quot;Failed to convert text!\n&quot;);
          }
          FreeMem(buf, BUF_SIZE);
        }
        else
          fprintf(stderr, &quot;Failed to allocate %d bytes for buffer\n&quot;, BUF_SIZE);
      }
      else
        fprintf(stderr, &quot;Unknown destination codeset %s\n&quot;, argv[2]);
    }
    else
      fprintf(stderr, &quot;Unknown source codeset %s\n&quot;, argv[1]);

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
  }
  else
    fprintf(stderr, &quot;Failed to open codesets.library!\n&quot;);

  return 0;
}
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;proto/exec.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define ISO8859_1_STR &quot;Schmöre bröd, schmöre bröd, bröd bröd bräd.&quot;
#define CP1251_STR    &quot;1251 êîäèðîâêà äëÿ ïðèìåðà.&quot;
#define ASCII_STR     &quot;latin 1 bla bla bla.&quot;
#define KOI8R_STR     &quot;koi îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace* ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

int main(void)
{
  int res;

  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
      GETINTERFACE(ICodesets, CodesetsBase))
  {
    IPTR errNum = 0;
    struct codeset *cs;

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ISO8859_1_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              TAG_DONE)))
    {
      printf(&quot;Identified ISO8859_1_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ISO8859_1_STR));
    }
    else
      printf(&quot;couldn't identify ISO8859_1_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)CP1251_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified CP1251_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(CP1251_STR));
    }
    else
      printf(&quot;couldn't identify CP1251_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ASCII_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified ASCII_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ASCII_STR));
    }
    else
      printf(&quot;couldn't identify ASCII_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)KOI8R_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified KOI8R_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(KOI8R_STR));
    }
    else
      printf(&quot;couldn't identify KOI8R_STR!\n&quot;);

    res = 0;

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
    CodesetsBase = NULL;
  }
  else
  {
    printf(&quot;can't open %s %d+\n&quot;,CODESETSNAME,CODESETSVER);
    res = 20;
  }

  return res;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


From [https://github.com/sba1/simplemail SimpleMail] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************
 SimpleMail - Copyright (C) 2000 Hynek Schlawack and Sebastian Bauer

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
***************************************************************************/

/**
 * @brief Support of codesets.
 *
 * @file codesets.c
 */

#include &quot;codesets.h&quot;

#include &lt;ctype.h&gt;
#include &lt;dirent.h&gt; /* dir stuff */
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;unistd.h&gt;

#include &quot;codesets_table.h&quot;
#include &quot;debug.h&quot;
#include &quot;punycode.h&quot;
#include &quot;smintl.h&quot;
#include &quot;support_indep.h&quot;

/* from ConvertUTF.h */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8.  Header file.

    Several funtions are included here, forming a complete set of
    conversions between the three formats.  UTF-7 is not included
    here, but is handled in a separate source file.

    Each of these routines takes pointers to input buffers and output
    buffers.  The input buffers are const.

    Each routine converts the text between *sourceStart and sourceEnd,
    putting the result into the buffer between *targetStart and
    targetEnd. Note: the end pointers are *after* the last item: e.g.
    *(sourceEnd - 1) is the last item.

    The return result indicates whether the conversion was successful,
    and if not, whether the problem was in the source or target buffers.
    (Only the first encountered problem is indicated.)

    After the conversion, *sourceStart and *targetStart are both
    updated to point to the end of last text successfully converted in
    the respective buffers.

    Input parameters:
	sourceStart - pointer to a pointer to the source buffer.
		The contents of this are modified on return so that
		it points at the next thing to be converted.
	targetStart - similarly, pointer to pointer to the target buffer.
	sourceEnd, targetEnd - respectively pointers to the ends of the
		two buffers, for overflow checking only.

    These conversion functions take a ConversionFlags argument. When this
    flag is set to strict, both irregular sequences and isolated surrogates
    will cause an error.  When the flag is set to lenient, both irregular
    sequences and isolated surrogates are converted.

    Whether the flag is strict or lenient, all illegal sequences will cause
    an error return. This includes sequences such as: &lt;F4 90 80 80&gt;, &lt;C0 80&gt;,
    or &lt;A0&gt; in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
    must check for illegal sequences.

    When the flag is set to lenient, characters over 0x10FFFF are converted
    to the replacement character; otherwise (when the flag is set to strict)
    they constitute an error.

    Output parameters:
	The value &quot;sourceIllegal&quot; is returned from some routines if the input
	sequence is malformed.  When &quot;sourceIllegal&quot; is returned, the source
	value will point to the illegal value that caused the problem. E.g.,
	in UTF-8 when a sequence is malformed, it points to the start of the
	malformed sequence.

    Author: Mark E. Davis, 1994.
    Rev History: Rick McGowan, fixes &amp; updates May 2001.

------------------------------------------------------------------------ */

/* ---------------------------------------------------------------------
    The following 4 definitions are compiler-specific.
    The C standard does not guarantee that wchar_t has at least
    16 bits, so wchar_t is no less portable than unsigned short!
    All should be unsigned values to avoid sign extension during
    bit mask &amp; shift operations.
------------------------------------------------------------------------ */

typedef unsigned long	UTF32;	/* at least 32 bits */
typedef unsigned short	UTF16;	/* at least 16 bits */
typedef unsigned char	UTF8;	/* typically 8 bits */
typedef unsigned char	Boolean; /* 0 or 1 */

/* Some fundamental constants */
#define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
#define UNI_MAX_BMP (UTF32)0x0000FFFF
#define UNI_MAX_UTF16 (UTF32)0x0010FFFF
#define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF

typedef enum {
	conversionOK, 		/* conversion successful */
	sourceExhausted,	/* partial character in source, but hit end */
	targetExhausted,	/* insuff. room in target for conversion */
	sourceIllegal,		/* source sequence is illegal/malformed */
  sourceCorrupt,    /* source contains invalid UTF-7 */ /* addded */
} ConversionResult;

typedef enum {
	strictConversion = 0,
	lenientConversion
} ConversionFlags;

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags);

static Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);

/* --------------------------------------------------------------------- */

int utf8islegal(const char *source, const char *sourceend)
{
	return isLegalUTF8Sequence((const UTF8*)source, (const UTF8*)sourceend);
}

/* --------------------------------------------------------------------- */

/* ConvertUTF.c */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8. Source code file.
	Author: Mark E. Davis, 1994.
	Rev History: Rick McGowan, fixes &amp; updates May 2001.

    See the header file &quot;ConvertUTF.h&quot; for complete documentation.

------------------------------------------------------------------------ */


/*#include &quot;ConvertUTF.h&quot;*/
/*#ifdef CVTUTF_DEBUG*/
#include &lt;stdio.h&gt;
/*#endif*/

static const int halfShift	= 10; /* used for shifting by 10 bits */

static const UTF32 halfBase	= 0x0010000UL;
static const UTF32 halfMask	= 0x3FFUL;

#define UNI_SUR_HIGH_START	(UTF32)0xD800
#define UNI_SUR_HIGH_END	(UTF32)0xDBFF
#define UNI_SUR_LOW_START	(UTF32)0xDC00
#define UNI_SUR_LOW_END		(UTF32)0xDFFF
#define false			0
#define true			1

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		ch = *source++;
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF32* target = *targetStart;
	UTF32 ch, ch2;
	while (source &lt; sourceEnd) {
		ch = *source++;
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			/* an unpaired low surrogate */
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		*target++ = ch;
	}
	*sourceStart = source;
	*targetStart = target;
#ifdef CVTUTF_DEBUG
if (result == sourceIllegal) {
    fprintf(stderr, &quot;ConvertUTF16toUTF32 illegal seq 0x%04x,%04x\n&quot;, ch, ch2);
    fflush(stderr);
}
#endif
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Index into the table below with the first byte of a UTF-8 sequence to
 * get the number of trailing bytes that are supposed to follow it.
 */

static const char trailingBytesForUTF8[256] = {
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
	2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, 3,3,3,3,3,3,3,3,4,4,4,4,5,5,5,5
};

/*
 * Magic values subtracted from a buffer value during UTF8 conversion.
 * This table contains as many values as there might be trailing bytes
 * in a UTF-8 sequence.
 */
static const UTF32 offsetsFromUTF8[6] = { 0x00000000UL, 0x00003080UL, 0x000E2080UL,
					 0x03C82080UL, 0xFA082080UL, 0x82082080UL };

/*
 * Once the bits are split out into bytes of UTF-8, this is a mask OR-ed
 * into the first byte, depending on how many bytes follow.  There are
 * as many entries in this table as there are UTF-8 sequence types.
 * (I.e., one byte sequence, two byte... six byte sequence.)
 */
static const UTF8 firstByteMark[7] = { 0x00, 0x00, 0xC0, 0xE0, 0xF0, 0xF8, 0xFC };

/* --------------------------------------------------------------------- */

/* The interface converts a whole buffer to avoid function-call overhead.
 * Constants have been gathered. Loops &amp; conditionals have been removed as
 * much as possible for efficiency, in favor of drop-through switches.
 * (See &quot;Note A&quot; at the bottom of the file for equivalent code.)
 * If your compiler supports it, the &quot;isLegalUTF8&quot; call can be turned
 * into an inline function.
 */

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* If we have a surrogate pair, convert to UTF32 first. */
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			UTF32 ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Utility routine to tell whether a sequence of bytes is legal UTF-8.
 * This must be called with the length pre-determined by the first byte.
 * If not calling this from ConvertUTF8to*, then the length can be set by:
 *	length = trailingBytesForUTF8[*source]+1;
 * and the sequence is illegal right away if there aren't that many bytes
 * available.
 * If presented with a length &gt; 4, this returns false.  The Unicode
 * definition of UTF-8 goes up to 4-byte sequences.
 */

static Boolean isLegalUTF8(const UTF8 *source, int length) {
	UTF8 a;
	const UTF8 *srcptr = source+length;
	switch (length) {
	default: return false;
		/* Everything else falls through when &quot;true&quot;... */
	case 4: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 3: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 2: if ((a = (*--srcptr)) &gt; 0xBF) return false;
		switch (*source) {
		    /* no fall-through in this inner switch */
		    case 0xE0: if (a &lt; 0xA0) return false; break;
		    case 0xF0: if (a &lt; 0x90) return false; break;
		    case 0xF4: if (a &gt; 0x8F) return false; break;
		    default:  if (a &lt; 0x80) return false;
		}
    	case 1: if (*source &gt;= 0x80 &amp;&amp; *source &lt; 0xC2) return false;
		if (*source &gt; 0xF4) return false;
	}
	return true;
}

/* --------------------------------------------------------------------- */

/*
 * Exported function to return whether a UTF-8 sequence is legal or not.
 * This is not used here; it's just exported.
 */
Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd) {
	int length = trailingBytesForUTF8[*source]+1;
	if (source+length &gt; sourceEnd) {
	    return false;
	}
	return isLegalUTF8(source, length);
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
				source -= extraBytesToRead; /* return to the start */
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* surrogates of any stripe are not legal UTF32 characters */
		if (flags == strictConversion ) {
			if ((ch &gt;= UNI_SUR_HIGH_START) &amp;&amp; (ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF32* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		} else {
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* ---------------------------------------------------------------------

	Note A.
	The fall-through switches in UTF-8 reading code save a
	temp variable, some decrements &amp; conditionals.  The switches
	are equivalent to the following loop:
		{
			int tmpBytesToRead = extraBytesToRead+1;
			do {
				ch += *source++;
				--tmpBytesToRead;
				if (tmpBytesToRead) ch &lt;&lt;= 6;
			} while (tmpBytesToRead &gt; 0);
		}
	In UTF-8 writing code, the switches on &quot;bytesToWrite&quot; are
	similarly unrolled loops.

   --------------------------------------------------------------------- */

/* Some code has been taken from the ConvertUTF7.c file (the utf7 stuff below),
   this is the copyright notice */

/* ================================================================ */
/*
File:   ConvertUTF7.c
Author: David B. Goldsmith
Copyright (C) 1994, 1996 IBM Corporation All rights reserved.
Revisions: Header update only July, 2001.

This code is copyrighted. Under the copyright laws, this code may not
be copied, in whole or part, without prior written consent of IBM Corporation.

IBM Corporation grants the right to use this code as long as this ENTIRE
copyright notice is reproduced in the code.  The code is provided
AS-IS, AND IBM CORPORATION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT
WILL IBM CORPORATION BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING,
WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY
LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THIS CODE, EVEN
IF IBM CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATION MAY NOT APPLY TO YOU.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the
government is subject to restrictions as set forth in subparagraph
(c)(l)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and FAR 52.227-19.

This code may be protected by one or more U.S. and International
Patents.

*/


/* ------------------------------------- */

struct list codesets_list;

/**************************************************************************
 Returns the supported codesets as an null terminated string array
**************************************************************************/
char **codesets_supported(void)
{
	static char **array;

	if (array) return array;

	if ((array = (char**)malloc(sizeof(char*)*(list_length(&amp;codesets_list)+1))))
	{
		struct codeset *code;
		int i;

		SM_DEBUGF(15,(&quot;%ld supported Codesets:\n&quot;,list_length(&amp;codesets_list)));

		code = (struct codeset*)list_first(&amp;codesets_list);
		i = 0;

		while (code)
		{
			SM_DEBUGF(15,(&quot;  %p next=%p prev=%p list=%p name=%p %s alt=%p char=%p\n&quot;,code,code-&gt;node.next,code-&gt;node.prev,code-&gt;node.list,code-&gt;name,code-&gt;name,code-&gt;alt_name,code-&gt;characterization));
			array[i++] = code-&gt;name;
			code = (struct codeset*)node_next(&amp;code-&gt;node);
		}
		array[i] = NULL;
	}
	return array;
}

/**************************************************************************
 The compare function
**************************************************************************/
static int codesets_cmp_unicode(const void *arg1, const void *arg2)
{
	char *a1 = (char*)((struct single_convert*)arg1)-&gt;utf8 + 1;
	char *a2 = (char*)((struct single_convert*)arg2)-&gt;utf8 + 1;
	return (int)strcmp(a1,a2);
}

/**
 * Reads the codeset table from the given filename and adds it.
 *
 * @param name
 * @return
 */
static int codesets_read_table(char *name)
{
	char buf[512];

	FILE *fh = fopen(name,&quot;r&quot;);

	if (fh)
	{
		struct codeset *codeset;
		if ((codeset = (struct codeset*)malloc(sizeof(struct codeset))))
		{
			int i;
			memset(codeset,0,sizeof(struct codeset));

			for (i=0;i&lt;256;i++)
				codeset-&gt;table[i].code = codeset-&gt;table[i].ucs4 = i;

			while (myreadline(fh,buf))
			{
				char *result;
				if ((result = get_key_value(buf,&quot;Standard&quot;))) codeset-&gt;name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;AltStandard&quot;))) codeset-&gt;alt_name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;ReadOnly&quot;))) codeset-&gt;read_only = !!atoi(result);
				else if ((result = get_key_value(buf,&quot;Characterization&quot;)))
				{
					if ((result[0] == '_') &amp;&amp; (result[1] == '(') &amp;&amp; (result[2] == '&quot;'))
					{
						char *end = strchr(result+3,'&quot;');
						if (end)
						{
							char *txt = mystrndup(result+3,end-(result+3));
							if (txt) codeset-&gt;characterization = mystrdup(_(txt));
							free(txt);
						}
					}
				} else
				{
					char *p = buf;
					int fmt2 = 0;

					if ((*p == '=') || (fmt2 = ((*p == '0') || (*(p+1)=='x'))))
					{
						p++;
						p += fmt2;

						i = strtol(p,&amp;p,16);
						if (i &gt; 0 &amp;&amp; i &lt; 256)
						{
							while (isspace((unsigned char)*p)) p++;

							if (!mystrnicmp(p,&quot;U+&quot;,2))
							{
								p += 2;
								codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,16);
							} else
							{
								if (*p!='#') codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,0);
							}
						}
					}
				}
			}

			for (i=0;i&lt;256;i++)
			{
				UTF32 src = codeset-&gt;table[i].ucs4;
				UTF32 *src_ptr = &amp;src;
				UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];
				ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
				*dest_ptr = 0;
				codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
			}

			memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
			qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
			list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);
		}
		fclose(fh);
	}
	return 1;
}

/*****************************************************************************/

int codesets_init(void)
{
	int i;
	struct codeset *codeset;
	UTF32 src;

	SM_ENTER;

	list_init(&amp;codesets_list);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 0;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1 + Euro&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European (with EURO)&quot;));
	codeset-&gt;read_only = 1;

	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i==164) src = 0x20AC; /* the EURO sign */
		else src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-2&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Central/East European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_2_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-3&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_3_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-4&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;North European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_4_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;KOI8-R&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Russian&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0x80) src = i;
		else src = koi8r_to_ucs4[i-0x80];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-5&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Slavic languages&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_5_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-9&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Turkish&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_9_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-15&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European II&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_15_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-16&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South-Eastern European&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_16_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amigapl_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amiga1251_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	SM_DEBUGF(15,(&quot;%ld internal charsets\n&quot;,list_length(&amp;codesets_list)));

	{
		/* dynamicaly loaded */

		DIR *dfd; /* directory descriptor */
		struct dirent *dptr; /* dir entry */
		char path[380];

		getcwd(path, sizeof(path));
		if (chdir(SM_CHARSET_DIR) != -1)
		{
			if ((dfd = opendir(SM_CURRENT_DIR)))
			{
				while ((dptr = readdir(dfd)) != NULL)
				{
					if (!strcmp(&quot;.&quot;,dptr-&gt;d_name) || !strcmp(&quot;..&quot;,dptr-&gt;d_name)) continue;
					SM_DEBUGF(15,(&quot;Loading \&quot;%s\&quot; charset\n&quot;,dptr-&gt;d_name,list_length(&amp;codesets_list)));
					codesets_read_table(dptr-&gt;d_name);
				}
				closedir(dfd);
			}
			chdir(path);
		}
	}

	SM_RETURN(1,&quot;%ld&quot;);
}

/*****************************************************************************/

void codesets_cleanup(void)
{
	struct codeset *codeset;

	while ((codeset = (struct codeset*)list_remove_tail(&amp;codesets_list)))
	{
		free(codeset-&gt;name);
		free(codeset-&gt;alt_name);
		free(codeset-&gt;characterization);
		free(codeset);
	}
}

/*****************************************************************************/

struct codeset *codesets_find(const char *name)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);

	/* Return ISO-8859-1 as default codeset */
	if (!name) return codeset;

	while (codeset)
	{
		if (!mystricmp(name,codeset-&gt;name) || !mystricmp(name,codeset-&gt;alt_name)) return codeset;
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}
	return NULL;
}

/*****************************************************************************/

int codesets_unconvertable_chars(struct codeset *codeset, const char *text, int text_len)
{
	struct single_convert conv;
	const char *text_ptr = text;
	int i;
	int errors = 0;

	for (i=0;i &lt; text_len;i++)
	{
		unsigned char c = *text_ptr++;
		if (c)
		{
			int len = trailingBytesForUTF8[c];
			conv.utf8[1] = c;
			strncpy((char*)&amp;conv.utf8[2],text_ptr,len);
			conv.utf8[2+len] = 0;
			text_ptr += len;

			if (!bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode))
				errors++;
		} else break;
	}

	return errors;
}

/*****************************************************************************/

struct codeset *codesets_find_best(const char *text, int text_len, int *error_ptr)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);
	struct codeset *best_codeset = NULL;
	int best_errors = text_len;

	while (codeset)
	{
		if (!codeset-&gt;read_only)
		{
			int errors = codesets_unconvertable_chars(codeset, text, text_len);

			if (errors &lt; best_errors)
			{
				best_codeset = codeset;
				best_errors = errors;
			}
			if (!best_errors) break;
		}
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}

	if (!best_codeset) best_codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (error_ptr) *error_ptr = best_errors;

	return best_codeset;
}

/*****************************************************************************/

int utf8len(const utf8 *str)
{
	int len ;
	unsigned char c;

	if (!str) return 0;
	len = 0;

	while ((c = *str++))
	{
		len++;
		str += trailingBytesForUTF8[c];
	}

	return len;
}

/*****************************************************************************/

utf8 *utf8dup(const utf8 *str)
{
	return (utf8*)mystrdup((char*)str);
}

/*****************************************************************************/

int utf8realpos(const utf8 *str, int pos)
{
	const utf8 *str_save = str;
	unsigned char c;

	if (!str) return 0;

	while (pos &amp;&amp; (c = *str))
	{
		pos--;
		str += trailingBytesForUTF8[c] + 1;
	}
	return str - str_save;
}

/*****************************************************************************/

int utf8charpos(const utf8 *str, int pos)
{
	int cp = 0;
	unsigned char c;

	while (pos &gt; 0 &amp;&amp; (c = *str))
	{
		str += trailingBytesForUTF8[c] + 1;
		pos -= trailingBytesForUTF8[c] + 1;
		cp++;
	}
	return cp;
}

/*****************************************************************************/

int utf8bytes(const utf8 *str)
{
	unsigned char c = *str;
	return trailingBytesForUTF8[c] + 1;
}

/*****************************************************************************/

utf8 *utf8ncpy(utf8 *to, const utf8 *from, int n)
{
	utf8 *saved_to = to;
	for (;n;n--)
	{
		unsigned char c = *from++;
		int len = trailingBytesForUTF8[c];

		*to++ = c;
		for (;len;len--)
		{
			*to++ = *from++;
		}
	}
	return saved_to;
}

/*****************************************************************************/

utf8 *utf8create(const void *from, const char *charset)
{
  /* utf8create_len() will stop on a null byte */
	return utf8create_len(from,charset,0x7fffffff);
}

/*****************************************************************************/

int utf8fromstr(const char *from, struct codeset *codeset, utf8 *dest, unsigned int dest_size)
{
	const char *src = from;
	unsigned char c;
	int conv = 0;

	if (dest_size &lt; 1)
		return 0;

	if (!codeset)
		codeset =  (struct codeset*)list_first(&amp;codesets_list);

	for (src = from;(c = (unsigned char)*src);src++)
	{
		unsigned char *utf8_seq;
		unsigned int l;

		utf8_seq = &amp;codeset-&gt;table[c].utf8[0];

		/* Recall that the first element represents
		 * the number of characters */
		l = utf8_seq[0];
		if (dest_size &lt;= l)
			break;

		utf8_seq++;
		for(;(c = *utf8_seq);utf8_seq++)
			*dest++ = c;

		dest_size -= l;
		conv++;
	}

	*dest = 0;
	return conv;
}

/*****************************************************************************/

utf8 *utf8create_len(const void *from, const char *charset, int from_len)
{
	int dest_size = 0;
	char *dest;
	char *src = (char*)from;
	unsigned char c;
	int len;
	struct codeset *codeset = codesets_find(charset);

	if (!from) return NULL;

	if (!codeset)
	{
		if (!mystricmp(charset,&quot;utf-7&quot;))
		{
			return (utf8*)utf7ntoutf8((char *)from,from_len);
		}
		if (!mystricmp(charset,&quot;utf-8&quot;))
		{
			return (utf8*)mystrdup((char *)from);
		}
		codeset = (struct codeset*)list_first(&amp;codesets_list);
	}

	len = from_len;

	while (((c = *src++) &amp;&amp; (len--)))
		dest_size += codeset-&gt;table[c].utf8[0];

	if ((dest = (char*)malloc(dest_size+1)))
	{
		char *dest_ptr = dest;

		for (src = (char*)from;from_len &amp;&amp; (c = *src);src++,from_len--)
		{
			unsigned char *utf8_seq;

			for(utf8_seq = &amp;codeset-&gt;table[c].utf8[1];(c = *utf8_seq);utf8_seq++)
				*dest_ptr++ = c;
		}

		*dest_ptr = 0;
		return (utf8*)dest;
	}
	return NULL;
}

/*****************************************************************************/

int utf8tostr(const utf8 *str, char *dest, unsigned int dest_size, struct codeset *codeset)
{
	unsigned int i;
	struct single_convert *f;
	char *dest_iter = dest;

	if (!dest_size)
	{
		return 0;
	}

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset || !str)
	{
		*dest = 0;
		return 0;
	}

	for (i=0;i &lt; dest_size-1;i++)
	{
		unsigned char c = *str;
		if (c)
		{
			if (c &gt; 127)
			{
				unsigned int len_add = trailingBytesForUTF8[c];
				unsigned int len_str = len_add + 1;

				BIN_SEARCH(codeset-&gt;table_sorted,0,255,mystrncmp((unsigned char*)str,codeset-&gt;table_sorted[m].utf8+1,len_str),f);

				if (f) *dest_iter++ = f-&gt;code;
				else *dest_iter++ = '_';

				str += len_add;
			} else *dest_iter++ = c;

			str++;
		} else break;
	}
	*dest_iter = 0;
	return i;
}

/*****************************************************************************/

char *utf8tostrcreate(const utf8 *str, struct codeset *codeset)
{
	char *dest;
	int len;
	if (!str) return NULL;
	len = strlen((char*)str);
	if ((dest = (char*)malloc(len+1)))
		utf8tostr(str,dest,len+1,codeset);
	return dest;
}

/*****************************************************************************/

int utf8tochar(const utf8 *str, unsigned int *chr, struct codeset *codeset)
{
	struct single_convert conv;
	struct single_convert *f;
	unsigned char c;
	int len = 0;

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset) return 0;

	if ((c = *str++))
	{
		int i;

		len = trailingBytesForUTF8[c];
		conv.utf8[1] = c;

		for (i=0;i&lt;len;i++)
		{
			if (!(conv.utf8[i+2] = *str++))
			{
				/* We encountered a 0 byte although the trailing byte suggested
				 * a different length. Hence the given utf8 sequence is not
				 * considered as valid */
				*chr = 0;
				return i+1;
			}
		}
		conv.utf8[2+len] = 0;

		if ((f = (struct single_convert*)bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode)))
		{
			*chr = f-&gt;code;
		} else *chr = 0;
	} else *chr = 0;
	return len+1;
}

/*****************************************************************************/

static inline int utf8cmp_single(unsigned char *a, unsigned char *b)
{
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
	int d;

	if ((d = a[0] - b[0])) return d;
	if ((d = a[1] - b[1])) return d;
	if ((d = a[2] - b[2])) return d;
	if ((d = a[3] - b[3])) return d;
	return 0;
#else
	return (*((unsigned int *)a) - *((unsigned int *)b));
#endif
}

/*****************************************************************************/

int utf8tolower(const char *str, char *dest)
{
	unsigned char ch[4] = {0,0,0,0};
	unsigned char c;
	struct uniconv *uc;
	int bytes;
	int i;

	c = *str++;
	if (c&lt;0x80)
	{
		*dest = tolower(c);
		return 1;
	}
	bytes = trailingBytesForUTF8[c];
	if (bytes &gt; 3)
	{
		*dest++ = c;
		memcpy(dest + 1,str + 1,bytes);
		return bytes + 1;
	}

	ch[3-bytes] = c;
	for (i=bytes-1;i&gt;=0;i--)
	{
		if (!(ch[3-i] = *str++))
			return 0;
	}

	BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),utf8cmp_single(utf8_tolower_table[m].from, ch),uc);

	if (uc)
		memcpy(dest, uc-&gt;to + 3 - bytes, bytes + 1);
	else
		memcpy(dest, ch + 3 - bytes, bytes + 1);
	return bytes + 1;
}

/*****************************************************************************/

int utf8stricmp(const char *str1, const char *str2)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (1)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8stricmp_len(const char *str1, const char *str2, int len)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (len&gt;0)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;
		len--;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;

				len--;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8match(const char *haystack, const char *needle, int case_insensitive, match_mask_t *match_mask)
{
	int h, n;
	int needle_len;
	int haystack_len;

	unsigned char hc;
	unsigned char nc;

	haystack_len = strlen(haystack);
	needle_len = strlen(needle);

	h = 0;
	n = 0;
	while (h &lt; haystack_len &amp;&amp; n &lt; needle_len)
	{
		int match;
		int hbytes;
		int nbytes;

		match = 0;
		hc = haystack[h];
		nc = needle[n];

		hbytes = trailingBytesForUTF8[hc];
		nbytes = trailingBytesForUTF8[nc];

		if (hbytes == nbytes)
		{
			if (hc == nc)
			{
				int i;

				match = 1;

				for (i=0; i &lt; hbytes; i++)
				{
					if (haystack[i+1] != needle[i+1])
						match = 0;
				}
			} else
			{
				if (hbytes == 0 &amp;&amp; case_insensitive)
				{
					if (tolower(hc) == tolower(nc))
					{
						match = 1;
					}
				}
			}

			if (!match &amp;&amp; case_insensitive &amp;&amp; hbytes &gt; 0)
			{
				char hchars[6] = {0};
				char nchars[6] = {0};
				int hl, nl;

				if ((hl = utf8tolower(&amp;haystack[h], hchars)) &gt; 0 &amp;&amp;
					(nl = utf8tolower(&amp;needle[n], nchars)) &gt; 0)
				{
					if (hl == nl)
					{
						match = memcmp(hchars, nchars, nl) == 0;
					}
				}

			}
		}

		if (match)
		{
			n += nbytes + 1;
		}

		if (match_mask)
		{
			unsigned int match_pos;

			match_pos = match_bitmask_pos(h);
			if (match)
			{
				match_mask[match_pos] |= match_bitmask(h);
			} else
			{
				match_mask[match_pos] &amp;= ~match_bitmask(h);
			}
		}

		h += hbytes + 1;
	}

	if (n == needle_len)
	{
		if (match_mask)
		{
			/* Make sure that the remaining relevant positions are cleared */
			for (;h &lt; haystack_len; h++)
			{
				match_mask[match_bitmask_pos(h)] &amp;= ~match_bitmask(h);
			}
		}
		return 1;
	}
	return 0;
}

/*****************************************************************************/

char *utf8stristr(const char *str1, const char *str2)
{
	int str2_len;

	if (!str1 || !str2) return NULL;

	str2_len = strlen(str2);

	while (*str1)
	{
		if (!utf8stricmp_len(str1,str2,str2_len))
			return (char*)str1;
		str1++;
	}
	return NULL;
}

/*****************************************************************************/

const char *uft8toucs(const char *chr, unsigned int *code)
{
	unsigned char c = *chr++;
	unsigned int ucs = 0;
	int i,bytes;
	if (!(c &amp; 0x80))
	{
		*code = c;
		return chr;
	} else
	{
		if (!(c &amp; 0x20))
		{
			bytes = 2;
			ucs = c &amp; 0x1f;
		}
		else if (!(c &amp; 0x10))
		{
			bytes = 3;
			ucs = c &amp; 0xf;
		}
		else if (!(c &amp; 0x08))
		{
			bytes = 4;
			ucs = c &amp; 0x7;
		}
		else if (!(c &amp; 0x04))
		{
			bytes = 5;
			ucs = c &amp; 0x3;
		}
		else /* if (!(c &amp; 0x02)) */
		{
			bytes = 6;
			ucs = c &amp; 0x1;
		}

		for (i=1;i&lt;bytes;i++)
			ucs = (ucs &lt;&lt; 6) | ((*chr++)&amp;0x3f);
	}
	*code = ucs;
	return chr;
}

static unsigned char base64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/&quot;;
static short invbase64[128];

static unsigned char ibase64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,&quot;;
static short iinvbase64[128];

static unsigned char direct[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'(),-./:?&quot;;
static unsigned char optional[] = &quot;!\&quot;#$%&amp;*;&lt;=&gt;@[]^_`{|}&quot;;
static unsigned char spaces[] = &quot; \011\015\012&quot;;		/* space, tab, return, line feed */
static char mustshiftsafe[128];
static char mustshiftopt[128];

static int needtables = 1;

static void tabinit(void)
{
	int i, limit;

	for (i = 0; i &lt; 128; ++i)
	{
		mustshiftopt[i] = mustshiftsafe[i] = 1;
		invbase64[i] = -1;
	}
	limit = strlen((char*)direct);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[direct[i]] = mustshiftsafe[direct[i]] = 0;
	limit = strlen((char*)spaces);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[spaces[i]] = mustshiftsafe[spaces[i]] = 0;
	limit = strlen((char*)optional);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[optional[i]] = 0;
	limit = strlen((char*)base64);
	for (i = 0; i &lt; limit; ++i)
		invbase64[base64[i]] = i;

	/* that's for the modified imap utf7 stuff */
	limit = strlen((char*)ibase64);
	for (i = 0; i &lt; limit; ++i)
		iinvbase64[ibase64[i]] = i;

	needtables = 0;
}

#if __cplusplus &gt;= 201703L
#define DECLARE_BIT_BUFFER unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#else
#define DECLARE_BIT_BUFFER register unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#endif

#define BITS_IN_BUFFER bufferbits
#define WRITE_N_BITS(x, n) ((BITbuffer |= ( ((x) &amp; ~(-1L&lt;&lt;(n))) &lt;&lt; (32-(n)-bufferbits) ) ), bufferbits += (n) )
#define READ_N_BITS(n) ((buffertemp = (BITbuffer &gt;&gt; (32-(n)))), (BITbuffer &lt;&lt;= (n)), (bufferbits -= (n)), buffertemp)

/*****************************************************************************/

char *utf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '+' || c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('+',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '+')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8toiutf7(char *utf8, int sourcelen)
{
	FILE *fh;
	char *dest = NULL;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;
		int shifted = 0;
		DECLARE_BIT_BUFFER;

		while (1)
		{
			unsigned char c;
			int noshift;

			if (sourcelen)
			{
				c = *utf8;
				noshift = (c &gt;= 0x20 &amp;&amp; c &lt;= 0x7e) &amp;&amp; (c != '&amp;');
			} else
			{
				c = 0;
				noshift = 1;
			}

			if (shifted)
			{
				while (BITS_IN_BUFFER &gt;= 6)
				{
					unsigned char bits = READ_N_BITS(6);
					fputc(ibase64[bits],fh);
				}

				if (noshift)
				{
					int bits_in_buf = BITS_IN_BUFFER;

					if (bits_in_buf)
					{
						unsigned char bits = READ_N_BITS(bits_in_buf);
						bits &lt;&lt;= 6 - bits_in_buf;
						fputc(ibase64[bits],fh);
					}
					shifted = 0;
					fputc('-',fh);
				}
			}

			if (!c) break;

			if (noshift)
			{
				if (c == '&amp;')
				{
					fputs(&quot;&amp;-&quot;,fh);
				} else fputc(c,fh);
				utf8++;
				sourcelen--;
			} else
			{
				UTF8 *source = (UTF8*)utf8;
				UTF16 dest = 0;
				UTF16 *dest_ptr = &amp;dest;
				ConversionResult res;

				res = ConvertUTF8toUTF16(&amp;source, source + sourcelen, &amp;dest_ptr, dest_ptr + 1, strictConversion);
				if (res == conversionOK || res == targetExhausted)
				{
					sourcelen -= trailingBytesForUTF8[c] + 1;
					utf8 += trailingBytesForUTF8[c] + 1;

					if (!shifted)
					{
						fputc('&amp;',fh);
						shifted = 1;
					}

					WRITE_N_BITS(dest,16);
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}
	return dest;
}

/*****************************************************************************/

char *iutf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('&amp;',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '&amp;')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8topunycode(const utf8 *source, int sourcelen)
{
	enum punycode_status status;
	const utf8 *sourceend;
	char *puny;
	punycode_uint puny_len;

	punycode_uint *dest, *target;
	punycode_uint dest_len;

	if (!(dest = (punycode_uint *)malloc(sourcelen * sizeof(punycode_uint))))
		return NULL;

	target = dest;
	sourceend = source + sourcelen;

	while (source &lt; sourceend)
	{
		punycode_uint ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*(UTF8*)source];

		if (source + extraBytesToRead &gt;= sourceend)
		{
			/* source exhausted */
			free(dest);
			return NULL;
		}

		/* Do this check whether lenient or strict */
		if (!isLegalUTF8((UTF8*)source, extraBytesToRead+1))
		{
			free(dest);
			return NULL;
		}

		/*
		 * The cases all fall through.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		}
	}

	dest_len = target - dest; /* No 0 ending */
	puny_len = dest_len * 2;

	do
	{
		int strored_puny_len = puny_len;

		if (!(puny = (char*)malloc(puny_len+5)))
		{
			free(dest);
			return NULL;
		}
		status = punycode_encode(dest_len, dest, NULL /* case flags */, &amp;puny_len, puny);

		if (status == punycode_success)
		{
			puny[puny_len] = 0;
			free(dest);
			return puny;
		}
		puny_len = strored_puny_len * 2;
	} while (status == punycode_big_output);

	free(puny);
	free(dest);
	return NULL;
}
/*****************************************************************************/

utf8 *punycodetoutf8(const char *source, int sourcelen)
{
	enum punycode_status status;
	punycode_uint *utf32;
	punycode_uint length;

	length = sourcelen;

	if (!(utf32 = (punycode_uint*)malloc(sizeof(punycode_uint)*sourcelen)))
		return NULL;

	status = punycode_decode(sourcelen, source, &amp;length, utf32, NULL);
	if (status == punycode_success)
	{
		utf8 *dest = (utf8*)malloc(sourcelen * 4);
		if (dest)
		{
			UTF8 *dest_start = (UTF8*)dest;
			UTF32 *source_start = (UTF32*)utf32;

			ConvertUTF32toUTF8((UTF32**)&amp;source_start, (UTF32*)(utf32) + length, &amp;dest_start, dest_start + sourcelen * 4 - 2, strictConversion);
			*dest_start = 0;
			free(utf32);
			return dest;
		}
	}
	free(utf32);
	return NULL;
}

/*****************************************************************************/

int isascii7(const char *str)
{
	char c;
	if (!str) return 1;
	while ((c = *str++))
	{
		if (c &amp; 0x80) return 0;
	}
	return 1;
}
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


== Library Calls ==

&lt;pre&gt;
TABLE OF CONTENTS

codesets.library/codesets.library
codesets.library/CodesetsSupportedA
codesets.library/CodesetsFindA
codesets.library/CodesetsFindBestA
codesets.library/CodesetsConvertStrA
codesets.library/CodesetsFreeA
codesets.library/CodesetsFreeVecPooledA
codesets.library/CodesetsSetDefaultA
codesets.library/CodesetsListCreateA
codesets.library/CodesetsListDeleteA
codesets.library/CodesetsListAddA
codesets.library/CodesetsListRemoveA
codesets.library/CodesetsUTF8CreateA
codesets.library/CodesetsUTF8ToStrA
codesets.library/CodesetsUTF8Len
codesets.library/CodesetsIsValidUTF8
codesets.library/CodesetsIsLegalUTF8
codesets.library/CodesetsIsLegalUTF8Sequence
codesets.library/CodesetsStrLenA
codesets.library/CodesetsConvertUTF16toUTF32
codesets.library/CodesetsConvertUTF16toUTF8
codesets.library/CodesetsConvertUTF32toUTF16
codesets.library/CodesetsConvertUTF32toUTF8
codesets.library/CodesetsConvertUTF8toUTF16
codesets.library/CodesetsConvertUTF8toUTF32
codesets.library/CodesetsDecodeB64A
codesets.library/CodesetsEncodeB64A


codesets.library/codesets.library

    *******************************************************************
    Copyright (c) 2005-2008 by codesets.library Open Source Team
    $Id$
    $URL$

    codesets.library is an AmigaOS shared library which provides
    functions to deal with different kind of codesets. It provides
    general character conversion routines, e.g. for converting
    from one charset (e.g. UTF8) into another (e.g. ISO-8859-1) or
    vice versa.

    codesets.library is mainly based on some code from UNICODE, some
    code from the SimpleMail project as well as some additions done
    by the codesets.library Open Source Team.

    It is released and distributed under the terms of the GNU Lesser
    General Public License (LGPL) and available free of charge.

    Please visit http://www.sf.net/projects/codesetslib/ for
    the very latest version and information regarding codesets.library.
    *******************************************************************

    For some short introduction on how to use codesets.library, the
    following pharagraph should provide a good summary. What you
    usually want to do with codesets.library is, to convert strings from
    one so-called &quot;Source Codeset&quot; into another &quot;Destination Codeset&quot;.
    The following list are only the main functions provided to
    developers, wanting to achieve this conversion in their applications:


    CodesetsSupportedA()
    --------------------

      For querying codesets library which codesets/charsets it supports
      either by its internal available charsets or by having obtained
      them from the operating system (e.g. AmigaOS4), this function
      can be used.

      E.g. in a MUI application you would do something like:

      -- cut here --
      STRPTR *array;

      if((array = CodesetsSupportedA(NULL)))
      {
        DoMethod(list, MUIM_List_Insert, array, -1, MUIV_List_Insert_Sorted);
        CodesetsFreeA(array, NULL);
      }
      -- cut here --


    CodesetsFindA()
    ---------------

      For processing/converting a specific string, you normally have to
      specify in which codeset this string has to be intepreted. For this
      purpose you have to pass a so-called &quot;Source Codeset&quot; to the main
      function of codesets.library. With the &quot;CodesetsFindA()&quot; function you
      can query codesets.library for providing you a pointer to the
      corresponding codeset structure which you afterwards will forward to
      the main conversion routines later on.

      For receiving the pointer to the Amiga-1251 codeset:
      -- cut here --
      struct codeset *cs;

      if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                            CSA_FallbackToDefault, FALSE,
                            TAG_DONE)))
      {
        ...
      }
      -- cut here --

      For querying codesets.library for the currently used system wide
      default of your running operating system:
      -- cut here --
      struct codeset *default;

      if((default = CodesetsFindA(NULL, NULL)))
      {
        ...
      }
      -- cut here --


    CodesetsConvertStrA()
    ---------------------

      The more or less most common function to use in codesets.library is
      definitly this function. It allows to convert a string from
      one &quot;Source Codeset&quot; to another &quot;Destination Codeset&quot;. It takes
      the source string converts it internally into UTF8 if necessary and
      then directly convert the UTF8 to the specified destination codeset.

      To convert a string 'str' to a destination codeset:
      -- cut here --
      STRPTR destString;

      if((destString = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                          CSA_DestCodeset,   destCodeset,
                                          CSA_Source,        str,
                                          TAG_DONE)))
      {
        ....

        CodesetsFreeA(destString, NULL);
      }
      -- cut here --

   Even if the above functions should cover most of the common functionality
   an ordinary user of codesets.library would require, it supplies a lot more
   functions which in fact we will not go into detail here but present
   certain examples in the respective documentation section of each function.

   However, if you find the documentation is still too limited or you feel
   some major functionality is missing regarding dealing with codesets,
   please let us know so that we or even you can improve it.


   Your codesets.library Open Source Team.
   February 2006


codesets.library/CodesetsSupportedA

   NAME
    CodesetsSupportedA - returns names of supported codesets

   SYNOPSIS
    array = CodesetsSupportedA(attrs);
                               A0

    STRPTR * CodesetsSupportedA(struct TagItem *);

    array = CodesetsSupported(tag1, ...);
                              A0

    STRPTR * CodesetsSupported(Tag, ...);

   FUNCTION
    Returns a NULL terminated array of the supported codeset
    names. The array _must_ be freed with CodesetsFreeA().

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

     CSA_AllowMultibyteCodesets (BOOL)
       Include multibyte codesets (UTF8, UTF16, UTF32) in the
       generated names array.
       Default: TRUE

   RESULT
    array - the names array or NULL on an error.

   EXAMPLE
    For printing out all supported codeset names:

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      int i;

      for(i=0; array[i] != NULL; i++)
        printf(&quot;%s&quot;, array[i]);

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindA

   NAME
    CodesetsFindA - finds a codeset

   SYNOPSIS
    codeset = CodesetsFindA(name, attrs);
    D0                      A0    A1

    struct codeset * CodesetsFindA(STRPTR, struct TagItem *);

    codeset = CodesetsFind(name, tag1, ...);
    D0                     A0    A1

    struct codeset * CodesetsFind(STRPTR, Tag, ...);

   FUNCTION
    Finds and returns a codeset by its name. The data behind the
    pointer should be considered read-only and must not be altered
    in any way.

   INPUTS
    name - the codeset name (or alias) to find
    attrs - a list of additional tag items. Valid items are:

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied codeset name can't be found.
        Default: TRUE

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

   RESULT
    codeset - the codeset or NULL on an error

   EXAMPLE
     E.g. for receiving the pointer to the Amiga-1251 codeset:

     -- cut here --
     struct codeset *cs;

     if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                           CSA_FallbackToDefault, FALSE,
                           TAG_DONE)))
     {
       ...
     }
     -- cut here --

     For querying codesets.library for the currently used system
     wide default of your running operating system:
     -- cut here --
     struct codeset *default;

     if((default = CodesetsFindA(NULL, NULL)))
     {
       ...
     }
     -- cut here --

   NOTE
    Please note for querying the system's default codeset the
    method of finding this codeset is highly dependent on the way
    the operating system can be queried for it. E.g. on AmigaOS4
    the default codeset is queried with updated system functions,
    but for AmigaOS3 a static list of language&lt;&gt;codeset mappings
    is used.

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindBestA

   NAME
    CodesetsFindBestA - finds the best codeset matching a
                        string content.

   SYNOPSIS
    codeset = CodesetsFindBestA(attrs);
    D0                          A0

    struct codeset * CodesetsFindBestA(struct TagItem *);

    codeset = CodesetsFindBest(tag1, ...);
    D0                         A0

    struct codeset * CodesetsFindBest(Tag, ...);

   FUNCTION
    Returns the best found codeset for the given text in the supplied
    codeset family. In case no proper codeset for the supplied source string
    could be found, NULL is returned or the default codeset if the
    CSA_FallbackToDefault attribute is set to TRUE. In addition, in case
    the CSA_ErrPtr is given, the amount of failed identifications (chars)
    are returned.

   INPUTS
    attrs - a list of tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to check just a part
        Default: string length of CSA_Source

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found errors (not identifyable chars)
        Default: NULL

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

      CSA_CodesetFamily (ULONG)
        To narrow the analyze, a user might define the codeset family
        of which the supplied text might be composed of. The reason for
        this is, that there isn't a unique identification algorithm
        which can tell the codeset out of a given text. So to narrow
        the identification, the follow values might be specified:

          CSV_CodesetFamily_Latin    - Latin codeset family (e.g. ISO-8859-X)
          CSV_CodesetFamily_Cyrillic - Cyrillic codeset family (e.g. KOI8R)

        Default: CSV_CodesetFamily_Latin

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied text couldn't be identified
        Default: FALSE

   RESULT
    codeset - the best matching codeset or NULL in case a NULL pointer
              was supplied as the source string.

   EXAMPLE
     E.g. for receiving the pointer to 'best matching' codeset matching
     a KOI8-R string:

     -- cut here --
     struct codeset *cs;
     char str[] = &quot;îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;;
     int errPtr;

     if((cs = CodesetsFindBest(CSA_Source, str,
                               CSA_ErrPtr, &amp;errPtr,
                               CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                               CSA_FallBackToDefault, FALSE,
                               TAG_DONE)))
     {
       ... should return the KOI8-R codeset ...
     }
     -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsConvertStrA

   NAME
    CodesetsConvertStrA - converts a string from one source codeset to
                          another destination codeset.

   SYNOPSIS
    dest = CodesetsConvertStrA(attrs)
    D0                         A0

    STRPTR CodesetsConvertStrA(struct TagItem *);

    dest = CodesetsConvertStr(tag1, ...);
    D0                        A0

    STRPTR CodesetsConvertStr(Tag, ...);

   FUNCTION
    The function takes source string which is encoded in a so-called
    'Source codeset' and converts it immediately into an equivalent
    string which will be encoded in the corresponding 'Destination Codeset'.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_DestCodeset (struct codeset *)
        The codeset to which the source string should be converted to.
        Default: the system's default codeset

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string
        which is returned.

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    either a pointer to the generated destination string or NULL
    on a found error.

   EXAMPLE
    To convert an ISO-8859-1 encoded string 'src' into an Amiga-1251
    equivalent 'dst' string:
    -- cut here --
    STRPTR src, dst;
    struct codeset *srcCodeset, *dstCodeset;

    srcCodeset = CodesetsFindA(&quot;ISO-8859-1&quot;, NULL);
    dstCodeset = CodesetsFindA(&quot;Amiga-1251&quot;, NULL);

    if((dst = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                 CSA_DestCodeset,   dstCodeset,
                                 CSA_Source,        src,
                                 TAG_DONE)))
    {
      ....

      CodesetsFreeA(dst, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsFreeA


codesets.library/CodesetsFreeA

   NAME
    CodesetsFreeA - frees objects previously internally allocated
                    by codesets.library

   SYNOPSIS
    CodesetsFreeA(obj, attrs)
                  A0   A1
    void CodesetsFreeA(APTR, struct TagItem *);

    CodesetsFree(obj, tag1, ...);
                 A0   A1
    void CodesetsFree(APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library. E.g. using
    functions like CodesetsSupportedA() or CodesetsConvertStrA().

   INPUTS
    obj - the object to free
    attrs - a list of additional tag items. Currently non items.

   RESULT
    no result

   EXAMPLE

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      ...

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsSupportedA
    codesets.library/CodesetsConvertStrA


codesets.library/CodesetsFreeVecPooledA

   NAME
    CodesetsFreeVecPooledA - frees objects previously allocated
                             by methods supporting CSA_Pool

   SYNOPSIS
    CodesetsFreeVecPooledA(pool, obj, attrs)
                           A0    A1   A2
    void CodesetsFreeVecPooledA(APTR, APTR, struct TagItem *);

    CodesetsFreeVecPooled(pool, obj, tag1, ...);
                          A0    A1   A2
    void CodesetsFreeVecPooled(APTR, APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library via a
    private memory pool which was previously used on codesets
    functions via the CSA_Pool tag.

   INPUTS
    pool - pointer to the private memory pool
    obj - the object to free
    attrs - a list of additional tag items. Valid tags are:

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    no result

   EXAMPLE

    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsSetDefaultA

   NAME
    CodesetsSetDefaultA - sets the default codeset, overwriting
                          the system default if necessary.

   SYNOPSIS
    codeset = CodesetsSetDefaultA(name, attrs);
                                  A0    A1

    struct codeset * CodesetsSetDefaultA(STRPTR, struct TagItem *);

    codeset = CodesetsSetDefault(name, tag1, ...);
                                 A0    A1

    struct codeset * CodesetsSetDefault(STRPTR, Tag, ...);

   FUNCTION
    Sets the default codeset to name. The codeset will be stored in
    the environment variable 'codeset_default'.

   INPUTS
    name - the name of the codeset to set as default
    attrs - a list of additional tag items. Valid items are:

      CSA_Save (BOOL)
        If TRUE the codeset will be permanently saved and survives
        a reset. Otherwise the default setting will just last until
        the next reboot.
        Default: FALSE

   RESULT
    codeset - the codeset or NULL

   NOTE
    In case the operating system supports the direct query of the
    currently active system's default codeset, this function will
    still overwrite this setting. So by using this method a user may
    overwrite all system's setting and set a global default codeset
    for his machine no matter what the OS suggests. However, in case
    your operating sytsem perfectly supports the querying of the
    system's default codeset (e.g. AmigaOS4) you are adviced to use
    this function with care - or even avoid to use it at all.

   SEE ALSO
    codesets.library/CodesetsFindA


codesets.library/CodesetsListCreateA

   NAME
    CodesetsListCreateA - creates a private, task-wise codeset list
                          and returns it to the user for further reference.

   SYNOPSIS
    list = CodesetsListCreateA(attrs);
    D0                         A0

    struct codesetList * CodesetsListCreateA(struct TagItem *);

    list = CodesetsListCreate(tag1, ...);
    D0                        A0

    struct codesetList * CodesetsListCreateA(Tag, ...);

   FUNCTION
    This function allows to create a private, task-wise codeset list by
    loading charset files from either a whole directory tree, a specific
    charset file or even by using an existing codeset structure.
    By using this function, an application might load and carry its very
    own private charsets in parallel to the internal charsets of
    codeset.library. This way each application can provide a different
    codeset list to the user without having to load and manage these
    lists on their own.

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    list - the private codeset list or NULL on an error condition

   NOTE
    For convienence, if no tag item attribute at all is supplied to the
    function, codesets.library will try to load charsets from the
    corresponding &quot;PROGDIR:Charsets&quot; directoy and add found codeset to
    the list. However, in case a tag item is specified (no matter what
    kind) the PROGDIR: scanning will be omitted.

   EXAMPLE
    For loading all found charset files from PROGDIR:Charsets:

    -- cut here --
    struct codesetList *csList;

    if((csList = CodesetsListCreateA(NULL)))
    {
      STRPTR codesetArray = CodesetsSupported(CSA_CodesetList, csList,
                                              TAG_DONE);

      // codesetsArray should now also carry our private
      // codesets from PROGDIR:Charsets
      ...

      CodesetsListDeleteA(CSA_CodesetList, csList,
                          TAG_DONE);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA
    codesets.library/CodesetsListSupportedA
    codesets.library/CodesetsListFindA
    codesets.library/CodesetsListFindBestA


codesets.library/CodesetsListDeleteA

   NAME
    CodesetsListDeleteA - deletes/frees all resources of previously created
                          private codeset lists.

   SYNOPSIS
    result = CodesetsListDeleteA(attrs);
    D0                           A0

    BOOL CodesetsListDeleteA(struct TagItem *);

    result = CodesetsListDelete(tag1, ...);
    D0                          A0

    BOOL CodesetsListDelete(Tag, ...);

   FUNCTION
    This function deletes all resources (also the contained codeset
    structures per default) and frees the memory of previously allocated
    private codeset lists.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        Pointer to a previously created, private codeset list whos
        resources should be freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all contained codesets should also be freed/deleted,
        otherwise just frees the list object itself.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Please note that if you added an explicit codeset structure to more
    than two private codeset lists you may run into problems with you
    don't take care of this yourself. This is a dumb function which just
    walks through the list and frees all resources. Set CSA_FreeCodesets
    to FALSE in case you just want to free the list object.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA


codesets.library/CodesetsListAddA

   NAME
    CodesetsListAddA - allows to add additional codesets to an already
                       existing private codeset list previously created with
                       CodesetsListCreateA().

   SYNOPSIS
    result = CodesetsListAddA(attrs);
    D0                        A0

    BOOL CodesetsListAddA(struct TagItem *);

    result = CodesetsListAdd(tag1, ...);
    D0                       A0

    BOOL CodesetsListAdd(Tag, ...);

   FUNCTION
    This function allows to add additional codesets to an already existing
    private codeset list. Either codesets themself may be added directly, or
    the path to either a file or a directory may be specified from which
    additional codesets may be loaded from known charset files.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Be careful when adding one codeset to more than one codeset list as
    you may run into problems when freeing the list afterwards.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsListRemoveA

   NAME
    CodesetsListRemoveA - removes a single or multiple codesets from a
                          previously created codeset list.

   SYNOPSIS
    result = CodesetsListRemoveA(attrs);
    D0                           A0

    BOOL CodesetsListRemoveA(struct TagItem *);

    result = CodesetsListRemove(tag1, ...);
    D0                          A0

    BOOL CodesetsListRemove(Tag, ...);

   FUNCTION
    This function allows to remove single or multiple codesets from a
    previously created codeset list. The removed codeset structures will
    also be freed/deleted per default.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        Pointer to a codeset structure which should be removed from
        its corresponding list. Per default its resources will also
        be internally freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all supplied codesets should also be freed/deleted,
        otherwise the codesets will just be removed from their lists.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    The function will automatically prevent removal of codesets from the
    internal codeset list of codesets.library and will return FALSE in
    case a user tried to remove a codeset from the internal list.

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsUTF8CreateA

   NAME
    CodesetsUTF8CreateA - creates an UTF8 compliant string
                          interpretation out of a supplied source
                          string.


   SYNOPSIS
    utf8 = CodesetsUTF8CreateA(attrs);
                               A0
    UTF8 * CodesetsUTF8CreateA(struct TagItem *);

    utf8 = CodesetsUTF8Create(tag1, ...);
                              A0
    UTF8 * CodesetsUTF8Create(Tag, ...);


   FUNCTION
    Creates an UTF8 from a string which is encoded in specified
    codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole utf8. If CSA_Dest can't
        contain the utf8, a brand new buffer is allocated. If
        CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the utf8 string

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the UTF8 a new buffer is allocated
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, utf8, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(utf8, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    utf8 - the utf8 string or NULL
           If CSA_DestHook is used always NULL.
           If CSA_DestHook is not used NULL means failure
           to allocate mem.

   EXAMPLE
    The shortest invocation is:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    In case you want to use your pool to allocate mem:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If your pool is to be arbitrated via a semaphore:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;
    struct SignalSemaphore *sem;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  CSA_PoolSem,    sem,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If you want to use your own buffer to reduce mem
    allocation:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[256];

    if((utf8 = CodesetsUTF8Create(CSA_Source,  str,
                                  CSA_Dest,    buf,
                                  CSA_DestLen, sizeof(buf),
                                  TAG_DONE)))
    {
        ...

        if(utf8 != buf)
          CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    If your string are max MAXLEN chars long (e.g. image to be
    in a MUI application and you know the max size of your
    string gadgets), you should better supply your own buffer:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[MAXSIZE*6+1];

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  CSA_Dest,   buf,
                                  CSA_Dest,   sizeof(buf),
                                  TAG_DONE)))
    {
        ...
    }
    -- cut here --


    If you strings are very large and so you are sure there is
    no mem for them and or you have your own reasons to do
    that:
    -- cut here --
    static ULONG ASM SAVEDS
    destFun(REG(a0, struct Hook *hook),
            REG(a2, struct convertMsg *msg),
            REG(a1, STRPTR buf))
    {
      printf(&quot;[%3ld] [%s]\n&quot;,msg-&gt;len,buf);
      if(msg-&gt;state == CSV_End)
        printf(&quot;\n&quot;);

      return 0;
    }

    struct Hook dest;
    dest.h_Entry = (HOOKFUNC)destFun;

    CodesetsUTF8Create(CSA_Source,    str,
                       CSA_DestHook,  &amp;dest,
                       TAG_DONE);
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8ToStrA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8ToStrA

   NAME
    CodesetsUTF8ToStrA - converts an UTF8 encoded string into
                         a specified destination codeset.


   SYNOPSIS
    str = CodesetsUTF8ToStrA(attrs);
    D0                       A0

    STRPTR CodesetsUTF8ToStrA(attrs);

    str = CodesetsUTF8ToStr(tag1, ...);
    D0                      A0

    STRPTR CodesetsUTF8ToStr(Tag,...);


   FUNCTION
    Convert an utf8 string to a specified codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source. Must be &gt; 0 or the function returns
        NULL.
        Default: string length of CSA_Source - strlen()

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole converted string. If CSA_Dest
        can't contain the output string, a brand new buffer is allocated.
        If CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestCodeset (struct codeset *)
        The codeset to which the UTF8 string should be encoded to.
        Default: the system's default codeset

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string.

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the output string, a new buffer is allocated.
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, string, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(string, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found issues (number of not convertable chars)
        Default: NULL

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    str - the string or NULL
          If CSA_DestHook is used always NULL.
          If CSA_DestHook is not used NULL means failure
          to allocate mem.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8Len

   NAME
    CodesetsUTF8Len - returns the length of a supplied utf8 string.

   SYNOPSIS
    len = CodesetsUTF8Len(utf8);
    D0                    A0

    ULONG CodesetsUTF8Len(UTF8 *);

   FUNCTION
    Returns the amount of real characters stored in a supplied UTF8
    string. This is _NOT_ the space required to store the UTF8 string,
    it is the actual number of _real_ character the UTF8 represents.

   INPUTS
    utf8 - pointer to the UTF8 string generated by the internal
           functions of codesets.library

   RESULT
    len - length of utf8

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsValidUTF8

   NAME
    CodesetsIsValidUTF8 - tells if a supplied standard string is meant to
                          carry a perfectly valid UTF8 sequence

   SYNOPSIS
    result = CodesetsIsValidUTF8(str);
    D0                           A0

    BOOL CodesetsIsValidUTF8(STRPTR);

   FUNCTION
    Returns TRUE in case the supplied string only contains char sequences
    which are compatible to the UTF8 standard.

   INPUTS
    str - a standard STRPTR string.

   RESULT
    result - TRUE in case the string conatins valid UTF8 data.

   NOTE
    This function uses the common 'GOOD_UCS' macro together with parsing
    the whole string. This means that it will only return TRUE in case
    the supplied string only contains UTF8 sequences. A mixture of UTF8
    and non-UTF8 sequences will result in the function returning FALSE.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8

   NAME
    CodesetsIsLegalUTF8 - check a UTF8 sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8(source, length);
                              A0      D0

    ULONG CodesetsIsLegalUTF8(UTF8 *, ULONG);


   FUNCTION
    Checks if source is a valid UTF8 sequence generated
    by the internal functions of codesets.library

   INPUTS
    source - the char sequence to check
    length - size of source

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8Sequence

   NAME
    CodesetsIsLegalUTF8Sequence - check a char sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8Sequence(source, end);
                                      A0      A1

    ULONG CodesetsIsLegalUTF8(UTF8 *, UTF8 *);

   FUNCTION
    Check if source is a valid UTF8 sequence within the
    source and end boundaries.

   INPUTS
    source - the char sequence to check
    end - pointer to the end of the sequence to check

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsStrLenA

   NAME
    CodesetsStrLenA - returns the length of the source string
                      in case it will be converted to an UTF8
                      string.

   SYNOPSIS
    len = CodesetsStrLenA(str, attrs)
                          A0   A1

    ULONG CodesetsStrLenA(STRPTR, struct TagItem *);

    len = CodesetsStrLen(str, tag1, ...);
                         A0   A1

    ULONG CodesetsStrLen(STRPTR, Tag, ...);

   FUNCTION
    Return the length (size) of str in case it will be converted to
    an UTF8 compliant string.

   INPUTS
    str - the string to obtain length of
    attrs - a list of additional tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        The codeset the source string is encoded in.
        Default: the system's default codeset

      CSA_SourceLen (ULONG)
        The length of str
        Default: string length of CSA_Source

   RESULT
    len - the length of the string if it will be converted to
          an UTF8 string.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA


codesets.library/CodesetsConvertUTF16toUTF32

   NAME
    CodesetsConvertUTF16toUTF32 - converts from UTF16 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF32(const UTF16 **,const UTF16 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF16toUTF8

   NAME
    CodesetsConvertUTF16toUTF8 - converts from UTF16 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF8(const UTF16 **,const UTF16 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF8.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF16

   NAME
    CodesetsConvertUTF32toUTF16 - converts from UTF32 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF16(const UTF32 **,const UTF32 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF8

   NAME
    CodesetsConvertUTF32toUTF8 - converts from UTF32 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF8(const UTF32 **,const UTF32 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF16

   NAME
    CodesetsConvertUTF8toUTF16 - converts from UTF8 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF16(const UTF8 **,const UTF8 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF32

   NAME
    CodesetsConvertUTF8toUTF32 - converts from UTF8 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF32(const UTF8 **,const UTF8 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsDecodeB64A

   NAME
    CodesetsDecodeB64A - decodes a supplied base64 encoded string
                         or file into plain text charwise.

   SYNOPSIS
    res = CodesetsDecodeB64A(attrs);
    D0                       A0

    ULONG CodesetsDecodeB64A(struct TagItem *);

    res = CodesetsDecodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsDecodeB64A(Tag, ....);

   FUNCTION
    Decodes a string or a complete base64 encoded file to a
    plain text buffer or also a destination file

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to decode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64FLG_NtCheckErr (BOOL)
        Don't stop on error.

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be still be encoded to.

   SEE ALSO
    codesets.library/CodesetsEncodeB64A


codesets.library/CodesetsEncodeB64A

   NAME
    CodesetsEncodeB64A - encodes a string or whole file
                         to base64

   SYNOPSIS
    res = CodesetsEncodeB64A(attrs);
    D0                       A0

    ULONG CodesetsEncodeB64A(struct TagItem *);

    res = CodesetsEncodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsEncodeB64(Tag, ....);

   FUNCTION
    Encodes the supplied string or file to either a whole
    buffer or also to a file.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to encode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString. Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64MaxLineLen (ULONG)
        Maximum length of encoded lines. 0&lt;v&lt;256
        Default: 72

      CSA_B64Unix (ULONG)
        If TRUE eol is \n (LF), otherwise \r\n (CRLF).
        Default: TRUE

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be encoded to.

   SEE ALSO
    codesets.library/CodesetsDecodeB64A

&lt;/pre&gt;</text>
      <sha1>fl9z373g352bf071ytv1qwqb9spkbo0</sha1>
    </revision>
    <revision>
      <id>4669775</id>
      <parentid>4669774</parentid>
      <timestamp>2026-09-12T17:11:30Z</timestamp>
      <contributor>
        <username>Jeff1138</username>
        <id>301139</id>
      </contributor>
      <minor />
      <origin>4669775</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="129471" sha1="430tv26chfy7wbpgddoq1e6c0eualh0" xml:space="preserve">{{ArosNav}}

==Introduction==

Character set (charsets) encoding is the process of assigning numbers to graphical characters, especially the written characters of human language

Unicode v16.0 emojis are not supported but [https://github.com/jens-maus/libcodesets codesets.library] provides 

&lt;pre&gt;
internally supported (hardcoded) charsets/codesets are: (conversions are possible from and to each codeset):

    AmigaPL – Polish (Amiga)
    Amiga-1251      – Cyrillic (Amiga)
    ISO-8859-1      – Latin 1 aka Western European ASCII based 
    ISO-8859-1+Euro – West European (with EURO)
    ISO-8859-2      – Latin-2 aka Central/East European
    ISO-8859-3      – South European
    ISO-8859-4      – North European
    ISO-8859-5      – Slavic languages
    ISO-8859-9      – Turkish
    ISO-8859-15     – West European II
    ISO-8859-16     – South-Eastern European
    KOI8-R – Russian
    UTF-8 – Unicode

In addition, external charset table files can be stored in LIBS:Charsets or loaded by an application from PROGDIR:Charsets. The charset files included with this distributions are:

    IBM866 – Cyrillic (cp866)
    ISO-8859-7 – Greek (LatinGreek)
    ISO-8859-10 – Nordic (Latin 6)
    windows-1250 – Central/East Europe (Windows)
    windows-1251 – Cyrillic (Windows)
    windows-1252 – West European (Windows)

Windows-1252 was first character set in Windows. It was a copy of ASCII, but used 8-bits to represent 256 different characters (international letters). Windows-1252 is supported by all browsers.
&lt;/pre&gt;


From [https://github.com/charabaruk/WookieChat Wookiechat]

Charsets: wookiechat doesnt need the incoming charset to be configured exactly anymore. When someone types weird characters, wookie will scan it for utf8 characters.. if it has those, then it'll convert it to ascii as best an Amiga can using codesets.library. if theres none, then it'll just use codesets.library Codesets_FindBest() function.


[https://github.com/jens-maus/yam YAM] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

[https://github.com/sacredbanana/AmigaGPT AmigaGPT]

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


==Source Code==

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;exec/libraries.h&gt;
#include &lt;libraries/codesets.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;proto/exec.h&gt;

#include &lt;stdio.h&gt;

/* This is just a very quickly written test, not a full-featured convertor */
#define BUF_SIZE 102400

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace *ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

struct codeset *srcCodeset;
struct codeset *destCodeset;

int main(int argc, char **argv)
{
  char *buf, *destbuf;
  ULONG destlen;
  FILE *f;

  if (argc &lt; 4)
  {
    fprintf(stderr, &quot;Usage: %s &lt;source codeset&gt; &lt;destination codeset&gt; &lt;source file&gt;\n&quot;, argv[0]);
    return 0;
  }
  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
     GETINTERFACE(ICodesets, CodesetsBase))
  {
    srcCodeset = CodesetsFind(argv[1], CSA_FallbackToDefault, FALSE, TAG_DONE);
    if (srcCodeset)
    {
      destCodeset = CodesetsFind(argv[2], CSA_FallbackToDefault, FALSE, TAG_DONE);
      if (destCodeset)
      {
        buf = AllocMem(BUF_SIZE, MEMF_CLEAR);

        if (buf)
        {
          f = fopen(argv[3], &quot;r&quot;);
          if (f)
          {
            fread(buf, BUF_SIZE-1, 1, f);
            fclose(f);
            destbuf = CodesetsConvertStr(CSA_SourceCodeset, (IPTR)srcCodeset,
                                         CSA_DestCodeset, (IPTR)destCodeset,
                                         CSA_Source, (IPTR)buf,
                                         CSA_DestLenPtr, (IPTR)&amp;destlen,
                                         TAG_DONE);
            if (destbuf)
            {
              fprintf(stderr, &quot;Result length: %u\n&quot;, (unsigned int)destlen);
              fwrite(destbuf, destlen, 1, stdout);
              fputc('\n', stderr);
              CodesetsFreeA(destbuf, NULL);
            }
          else
            fprintf(stderr, &quot;Failed to convert text!\n&quot;);
          }
          FreeMem(buf, BUF_SIZE);
        }
        else
          fprintf(stderr, &quot;Failed to allocate %d bytes for buffer\n&quot;, BUF_SIZE);
      }
      else
        fprintf(stderr, &quot;Unknown destination codeset %s\n&quot;, argv[2]);
    }
    else
      fprintf(stderr, &quot;Unknown source codeset %s\n&quot;, argv[1]);

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
  }
  else
    fprintf(stderr, &quot;Failed to open codesets.library!\n&quot;);

  return 0;
}
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************

 codesets.library - Amiga shared library for handling different codesets
 Copyright (C) 2001-2005 by Alfonso [alfie] Ranieri &lt;alforan@tin.it&gt;.
 Copyright (C) 2005-2014 codesets.library Open Source Team

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 codesets.library project: http://sourceforge.net/projects/codesetslib/

 Most of the code included in this file was relicensed from GPL to LGPL
 from the source code of SimpleMail (http://www.sf.net/projects/simplemail)
 with full permissions by its authors.

 $Id$

***************************************************************************/

#include &lt;proto/exec.h&gt;
#include &lt;proto/codesets.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define ISO8859_1_STR &quot;Schmöre bröd, schmöre bröd, bröd bröd bräd.&quot;
#define CP1251_STR    &quot;1251 êîäèðîâêà äëÿ ïðèìåðà.&quot;
#define ASCII_STR     &quot;latin 1 bla bla bla.&quot;
#define KOI8R_STR     &quot;koi îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;

struct Library *CodesetsBase = NULL;
#if defined(__amigaos4__)
struct CodesetsIFace* ICodesets = NULL;
#endif

#if defined(__amigaos4__)
#define GETINTERFACE(iface, base)	(iface = (APTR)GetInterface((struct Library *)(base), &quot;main&quot;, 1L, NULL))
#define DROPINTERFACE(iface)			(DropInterface((struct Interface *)iface), iface = NULL)
#else
#define GETINTERFACE(iface, base)	TRUE
#define DROPINTERFACE(iface)
#endif

int main(void)
{
  int res;

  if((CodesetsBase = OpenLibrary(CODESETSNAME,CODESETSVER)) &amp;&amp;
      GETINTERFACE(ICodesets, CodesetsBase))
  {
    IPTR errNum = 0;
    struct codeset *cs;

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ISO8859_1_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              TAG_DONE)))
    {
      printf(&quot;Identified ISO8859_1_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ISO8859_1_STR));
    }
    else
      printf(&quot;couldn't identify ISO8859_1_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)CP1251_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified CP1251_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(CP1251_STR));
    }
    else
      printf(&quot;couldn't identify CP1251_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)ASCII_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified ASCII_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(ASCII_STR));
    }
    else
      printf(&quot;couldn't identify ASCII_STR!\n&quot;);

    if((cs = CodesetsFindBest(CSA_Source, (IPTR)KOI8R_STR,
                              CSA_ErrPtr, (IPTR)&amp;errNum,
                              CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                              TAG_DONE)))
    {
      printf(&quot;Identified KOI8R_STR as %s with %d of %d errors\n&quot;, cs-&gt;name, (int)errNum, (int)strlen(KOI8R_STR));
    }
    else
      printf(&quot;couldn't identify KOI8R_STR!\n&quot;);

    res = 0;

    DROPINTERFACE(ICodesets);
    CloseLibrary(CodesetsBase);
    CodesetsBase = NULL;
  }
  else
  {
    printf(&quot;can't open %s %d+\n&quot;,CODESETSNAME,CODESETSVER);
    res = 20;
  }

  return res;
}
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


From [https://github.com/sba1/simplemail SimpleMail] 

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
/***************************************************************************
 SimpleMail - Copyright (C) 2000 Hynek Schlawack and Sebastian Bauer

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
***************************************************************************/

/**
 * @brief Support of codesets.
 *
 * @file codesets.c
 */

#include &quot;codesets.h&quot;

#include &lt;ctype.h&gt;
#include &lt;dirent.h&gt; /* dir stuff */
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;unistd.h&gt;

#include &quot;codesets_table.h&quot;
#include &quot;debug.h&quot;
#include &quot;punycode.h&quot;
#include &quot;smintl.h&quot;
#include &quot;support_indep.h&quot;

/* from ConvertUTF.h */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8.  Header file.

    Several funtions are included here, forming a complete set of
    conversions between the three formats.  UTF-7 is not included
    here, but is handled in a separate source file.

    Each of these routines takes pointers to input buffers and output
    buffers.  The input buffers are const.

    Each routine converts the text between *sourceStart and sourceEnd,
    putting the result into the buffer between *targetStart and
    targetEnd. Note: the end pointers are *after* the last item: e.g.
    *(sourceEnd - 1) is the last item.

    The return result indicates whether the conversion was successful,
    and if not, whether the problem was in the source or target buffers.
    (Only the first encountered problem is indicated.)

    After the conversion, *sourceStart and *targetStart are both
    updated to point to the end of last text successfully converted in
    the respective buffers.

    Input parameters:
	sourceStart - pointer to a pointer to the source buffer.
		The contents of this are modified on return so that
		it points at the next thing to be converted.
	targetStart - similarly, pointer to pointer to the target buffer.
	sourceEnd, targetEnd - respectively pointers to the ends of the
		two buffers, for overflow checking only.

    These conversion functions take a ConversionFlags argument. When this
    flag is set to strict, both irregular sequences and isolated surrogates
    will cause an error.  When the flag is set to lenient, both irregular
    sequences and isolated surrogates are converted.

    Whether the flag is strict or lenient, all illegal sequences will cause
    an error return. This includes sequences such as: &lt;F4 90 80 80&gt;, &lt;C0 80&gt;,
    or &lt;A0&gt; in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
    must check for illegal sequences.

    When the flag is set to lenient, characters over 0x10FFFF are converted
    to the replacement character; otherwise (when the flag is set to strict)
    they constitute an error.

    Output parameters:
	The value &quot;sourceIllegal&quot; is returned from some routines if the input
	sequence is malformed.  When &quot;sourceIllegal&quot; is returned, the source
	value will point to the illegal value that caused the problem. E.g.,
	in UTF-8 when a sequence is malformed, it points to the start of the
	malformed sequence.

    Author: Mark E. Davis, 1994.
    Rev History: Rick McGowan, fixes &amp; updates May 2001.

------------------------------------------------------------------------ */

/* ---------------------------------------------------------------------
    The following 4 definitions are compiler-specific.
    The C standard does not guarantee that wchar_t has at least
    16 bits, so wchar_t is no less portable than unsigned short!
    All should be unsigned values to avoid sign extension during
    bit mask &amp; shift operations.
------------------------------------------------------------------------ */

typedef unsigned long	UTF32;	/* at least 32 bits */
typedef unsigned short	UTF16;	/* at least 16 bits */
typedef unsigned char	UTF8;	/* typically 8 bits */
typedef unsigned char	Boolean; /* 0 or 1 */

/* Some fundamental constants */
#define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
#define UNI_MAX_BMP (UTF32)0x0000FFFF
#define UNI_MAX_UTF16 (UTF32)0x0010FFFF
#define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF

typedef enum {
	conversionOK, 		/* conversion successful */
	sourceExhausted,	/* partial character in source, but hit end */
	targetExhausted,	/* insuff. room in target for conversion */
	sourceIllegal,		/* source sequence is illegal/malformed */
  sourceCorrupt,    /* source contains invalid UTF-7 */ /* addded */
} ConversionResult;

typedef enum {
	strictConversion = 0,
	lenientConversion
} ConversionFlags;

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags);

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags);

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags);

static Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);

/* --------------------------------------------------------------------- */

int utf8islegal(const char *source, const char *sourceend)
{
	return isLegalUTF8Sequence((const UTF8*)source, (const UTF8*)sourceend);
}

/* --------------------------------------------------------------------- */

/* ConvertUTF.c */

/*
 * Copyright 2001 Unicode, Inc.
 *
 * Disclaimer
 *
 * This source code is provided as is by Unicode, Inc. No claims are
 * made as to fitness for any particular purpose. No warranties of any
 * kind are expressed or implied. The recipient agrees to determine
 * applicability of information provided. If this file has been
 * purchased on magnetic or optical media from Unicode, Inc., the
 * sole remedy for any claim will be exchange of defective media
 * within 90 days of receipt.
 *
 * Limitations on Rights to Redistribute This Code
 *
 * Unicode, Inc. hereby grants the right to freely use the information
 * supplied in this file in the creation of products supporting the
 * Unicode Standard, and to make copies of this file in any form
 * for internal or external distribution as long as this notice
 * remains attached.
 */

/* ---------------------------------------------------------------------

    Conversions between UTF32, UTF-16, and UTF-8. Source code file.
	Author: Mark E. Davis, 1994.
	Rev History: Rick McGowan, fixes &amp; updates May 2001.

    See the header file &quot;ConvertUTF.h&quot; for complete documentation.

------------------------------------------------------------------------ */


/*#include &quot;ConvertUTF.h&quot;*/
/*#ifdef CVTUTF_DEBUG*/
#include &lt;stdio.h&gt;
/*#endif*/

static const int halfShift	= 10; /* used for shifting by 10 bits */

static const UTF32 halfBase	= 0x0010000UL;
static const UTF32 halfMask	= 0x3FFUL;

#define UNI_SUR_HIGH_START	(UTF32)0xD800
#define UNI_SUR_HIGH_END	(UTF32)0xDBFF
#define UNI_SUR_LOW_START	(UTF32)0xDC00
#define UNI_SUR_LOW_END		(UTF32)0xDFFF
#define false			0
#define true			1

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF16 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		ch = *source++;
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF32 (
		UTF16** sourceStart, UTF16* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF32* target = *targetStart;
	UTF32 ch, ch2;
	while (source &lt; sourceEnd) {
		ch = *source++;
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			/* an unpaired low surrogate */
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		*target++ = ch;
	}
	*sourceStart = source;
	*targetStart = target;
#ifdef CVTUTF_DEBUG
if (result == sourceIllegal) {
    fprintf(stderr, &quot;ConvertUTF16toUTF32 illegal seq 0x%04x,%04x\n&quot;, ch, ch2);
    fflush(stderr);
}
#endif
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Index into the table below with the first byte of a UTF-8 sequence to
 * get the number of trailing bytes that are supposed to follow it.
 */

static const char trailingBytesForUTF8[256] = {
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
	1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
	2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, 3,3,3,3,3,3,3,3,4,4,4,4,5,5,5,5
};

/*
 * Magic values subtracted from a buffer value during UTF8 conversion.
 * This table contains as many values as there might be trailing bytes
 * in a UTF-8 sequence.
 */
static const UTF32 offsetsFromUTF8[6] = { 0x00000000UL, 0x00003080UL, 0x000E2080UL,
					 0x03C82080UL, 0xFA082080UL, 0x82082080UL };

/*
 * Once the bits are split out into bytes of UTF-8, this is a mask OR-ed
 * into the first byte, depending on how many bytes follow.  There are
 * as many entries in this table as there are UTF-8 sequence types.
 * (I.e., one byte sequence, two byte... six byte sequence.)
 */
static const UTF8 firstByteMark[7] = { 0x00, 0x00, 0xC0, 0xE0, 0xF0, 0xF8, 0xFC };

/* --------------------------------------------------------------------- */

/* The interface converts a whole buffer to avoid function-call overhead.
 * Constants have been gathered. Loops &amp; conditionals have been removed as
 * much as possible for efficiency, in favor of drop-through switches.
 * (See &quot;Note A&quot; at the bottom of the file for equivalent code.)
 * If your compiler supports it, the &quot;isLegalUTF8&quot; call can be turned
 * into an inline function.
 */

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF16toUTF8 (
		UTF16** sourceStart, const UTF16* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF16* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* If we have a surrogate pair, convert to UTF32 first. */
		if (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_HIGH_END &amp;&amp; source &lt; sourceEnd) {
			UTF32 ch2 = *source;
			if (ch2 &gt;= UNI_SUR_LOW_START &amp;&amp; ch2 &lt;= UNI_SUR_LOW_END) {
				ch = ((ch - UNI_SUR_HIGH_START) &lt;&lt; halfShift)
					+ (ch2 - UNI_SUR_LOW_START) + halfBase;
				++source;
			} else if (flags == strictConversion) { /* it's an unpaired high surrogate */
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		} else if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_LOW_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
			--source; /* return to the illegal value itself */
			result = sourceIllegal;
			break;
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

/*
 * Utility routine to tell whether a sequence of bytes is legal UTF-8.
 * This must be called with the length pre-determined by the first byte.
 * If not calling this from ConvertUTF8to*, then the length can be set by:
 *	length = trailingBytesForUTF8[*source]+1;
 * and the sequence is illegal right away if there aren't that many bytes
 * available.
 * If presented with a length &gt; 4, this returns false.  The Unicode
 * definition of UTF-8 goes up to 4-byte sequences.
 */

static Boolean isLegalUTF8(const UTF8 *source, int length) {
	UTF8 a;
	const UTF8 *srcptr = source+length;
	switch (length) {
	default: return false;
		/* Everything else falls through when &quot;true&quot;... */
	case 4: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 3: if ((a = (*--srcptr)) &lt; 0x80 || a &gt; 0xBF) return false;
	case 2: if ((a = (*--srcptr)) &gt; 0xBF) return false;
		switch (*source) {
		    /* no fall-through in this inner switch */
		    case 0xE0: if (a &lt; 0xA0) return false; break;
		    case 0xF0: if (a &lt; 0x90) return false; break;
		    case 0xF4: if (a &gt; 0x8F) return false; break;
		    default:  if (a &lt; 0x80) return false;
		}
    	case 1: if (*source &gt;= 0x80 &amp;&amp; *source &lt; 0xC2) return false;
		if (*source &gt; 0xF4) return false;
	}
	return true;
}

/* --------------------------------------------------------------------- */

/*
 * Exported function to return whether a UTF-8 sequence is legal or not.
 * This is not used here; it's just exported.
 */
Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd) {
	int length = trailingBytesForUTF8[*source]+1;
	if (source+length &gt; sourceEnd) {
	    return false;
	}
	return isLegalUTF8(source, length);
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF16 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF16** targetStart, const UTF16* targetEnd, const ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF16* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_BMP) { /* Target is a character &lt;= 0xFFFF */
			if ((flags == strictConversion) &amp;&amp; (ch &gt;= UNI_SUR_HIGH_START &amp;&amp; ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			} else {
			    *target++ = ch;	/* normal case */
			}
		} else if (ch &gt; UNI_MAX_UTF16) {
			if (flags == strictConversion) {
				result = sourceIllegal;
				source -= extraBytesToRead; /* return to the start */
			} else {
				*target++ = UNI_REPLACEMENT_CHAR;
			}
		} else {
			/* target is a character in range 0xFFFF - 0x10FFFF. */
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF32toUTF8 (
		UTF32** sourceStart, const UTF32* sourceEnd,
		UTF8** targetStart, const UTF8* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF32* source = *sourceStart;
	UTF8* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch;
		unsigned short bytesToWrite = 0;
		const UTF32 byteMask = 0xBF;
		const UTF32 byteMark = 0x80;
		ch = *source++;
		/* surrogates of any stripe are not legal UTF32 characters */
		if (flags == strictConversion ) {
			if ((ch &gt;= UNI_SUR_HIGH_START) &amp;&amp; (ch &lt;= UNI_SUR_LOW_END)) {
				--source; /* return to the illegal value itself */
				result = sourceIllegal;
				break;
			}
		}
		/* Figure out how many bytes the result will require */
		if (ch &lt; (UTF32)0x80) {			bytesToWrite = 1;
		} else if (ch &lt; (UTF32)0x800) {		bytesToWrite = 2;
		} else if (ch &lt; (UTF32)0x10000) {	bytesToWrite = 3;
		} else if (ch &lt; (UTF32)0x200000) {	bytesToWrite = 4;
		} else {				bytesToWrite = 2;
							ch = UNI_REPLACEMENT_CHAR;
		}

		target += bytesToWrite;
		if (target &gt; targetEnd) {
			target -= bytesToWrite; result = targetExhausted; break;
		}
		switch (bytesToWrite) {	/* note: everything falls through. */
			case 4:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 3:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 2:	*--target = (ch | byteMark) &amp; byteMask; ch &gt;&gt;= 6;
			case 1:	*--target =  ch | firstByteMark[bytesToWrite];
		}
		target += bytesToWrite;
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* --------------------------------------------------------------------- */

ConversionResult ConvertUTF8toUTF32 (
		UTF8** sourceStart, UTF8* sourceEnd,
		UTF32** targetStart, const UTF32* targetEnd, ConversionFlags flags) {
	ConversionResult result = conversionOK;
	UTF8* source = *sourceStart;
	UTF32* target = *targetStart;
	while (source &lt; sourceEnd) {
		UTF32 ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*source];
		if (source + extraBytesToRead &gt;= sourceEnd) {
			result = sourceExhausted; break;
		}
		/* Do this check whether lenient or strict */
		if (! isLegalUTF8(source, extraBytesToRead+1)) {
			result = sourceIllegal;
			break;
		}
		/*
		 * The cases all fall through. See &quot;Note A&quot; below.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (target &gt;= targetEnd) {
			result = targetExhausted; break;
		}
		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		} else {
			if (target + 1 &gt;= targetEnd) {
				result = targetExhausted; break;
			}
			ch -= halfBase;
			*target++ = (ch &gt;&gt; halfShift) + UNI_SUR_HIGH_START;
			*target++ = (ch &amp; halfMask) + UNI_SUR_LOW_START;
		}
	}
	*sourceStart = source;
	*targetStart = target;
	return result;
}

/* ---------------------------------------------------------------------

	Note A.
	The fall-through switches in UTF-8 reading code save a
	temp variable, some decrements &amp; conditionals.  The switches
	are equivalent to the following loop:
		{
			int tmpBytesToRead = extraBytesToRead+1;
			do {
				ch += *source++;
				--tmpBytesToRead;
				if (tmpBytesToRead) ch &lt;&lt;= 6;
			} while (tmpBytesToRead &gt; 0);
		}
	In UTF-8 writing code, the switches on &quot;bytesToWrite&quot; are
	similarly unrolled loops.

   --------------------------------------------------------------------- */

/* Some code has been taken from the ConvertUTF7.c file (the utf7 stuff below),
   this is the copyright notice */

/* ================================================================ */
/*
File:   ConvertUTF7.c
Author: David B. Goldsmith
Copyright (C) 1994, 1996 IBM Corporation All rights reserved.
Revisions: Header update only July, 2001.

This code is copyrighted. Under the copyright laws, this code may not
be copied, in whole or part, without prior written consent of IBM Corporation.

IBM Corporation grants the right to use this code as long as this ENTIRE
copyright notice is reproduced in the code.  The code is provided
AS-IS, AND IBM CORPORATION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT
WILL IBM CORPORATION BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING,
WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY
LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THIS CODE, EVEN
IF IBM CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATION MAY NOT APPLY TO YOU.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the
government is subject to restrictions as set forth in subparagraph
(c)(l)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and FAR 52.227-19.

This code may be protected by one or more U.S. and International
Patents.

*/


/* ------------------------------------- */

struct list codesets_list;

/**************************************************************************
 Returns the supported codesets as an null terminated string array
**************************************************************************/
char **codesets_supported(void)
{
	static char **array;

	if (array) return array;

	if ((array = (char**)malloc(sizeof(char*)*(list_length(&amp;codesets_list)+1))))
	{
		struct codeset *code;
		int i;

		SM_DEBUGF(15,(&quot;%ld supported Codesets:\n&quot;,list_length(&amp;codesets_list)));

		code = (struct codeset*)list_first(&amp;codesets_list);
		i = 0;

		while (code)
		{
			SM_DEBUGF(15,(&quot;  %p next=%p prev=%p list=%p name=%p %s alt=%p char=%p\n&quot;,code,code-&gt;node.next,code-&gt;node.prev,code-&gt;node.list,code-&gt;name,code-&gt;name,code-&gt;alt_name,code-&gt;characterization));
			array[i++] = code-&gt;name;
			code = (struct codeset*)node_next(&amp;code-&gt;node);
		}
		array[i] = NULL;
	}
	return array;
}

/**************************************************************************
 The compare function
**************************************************************************/
static int codesets_cmp_unicode(const void *arg1, const void *arg2)
{
	char *a1 = (char*)((struct single_convert*)arg1)-&gt;utf8 + 1;
	char *a2 = (char*)((struct single_convert*)arg2)-&gt;utf8 + 1;
	return (int)strcmp(a1,a2);
}

/**
 * Reads the codeset table from the given filename and adds it.
 *
 * @param name
 * @return
 */
static int codesets_read_table(char *name)
{
	char buf[512];

	FILE *fh = fopen(name,&quot;r&quot;);

	if (fh)
	{
		struct codeset *codeset;
		if ((codeset = (struct codeset*)malloc(sizeof(struct codeset))))
		{
			int i;
			memset(codeset,0,sizeof(struct codeset));

			for (i=0;i&lt;256;i++)
				codeset-&gt;table[i].code = codeset-&gt;table[i].ucs4 = i;

			while (myreadline(fh,buf))
			{
				char *result;
				if ((result = get_key_value(buf,&quot;Standard&quot;))) codeset-&gt;name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;AltStandard&quot;))) codeset-&gt;alt_name = mystrdup(result);
				else if ((result = get_key_value(buf,&quot;ReadOnly&quot;))) codeset-&gt;read_only = !!atoi(result);
				else if ((result = get_key_value(buf,&quot;Characterization&quot;)))
				{
					if ((result[0] == '_') &amp;&amp; (result[1] == '(') &amp;&amp; (result[2] == '&quot;'))
					{
						char *end = strchr(result+3,'&quot;');
						if (end)
						{
							char *txt = mystrndup(result+3,end-(result+3));
							if (txt) codeset-&gt;characterization = mystrdup(_(txt));
							free(txt);
						}
					}
				} else
				{
					char *p = buf;
					int fmt2 = 0;

					if ((*p == '=') || (fmt2 = ((*p == '0') || (*(p+1)=='x'))))
					{
						p++;
						p += fmt2;

						i = strtol(p,&amp;p,16);
						if (i &gt; 0 &amp;&amp; i &lt; 256)
						{
							while (isspace((unsigned char)*p)) p++;

							if (!mystrnicmp(p,&quot;U+&quot;,2))
							{
								p += 2;
								codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,16);
							} else
							{
								if (*p!='#') codeset-&gt;table[i].ucs4 = strtol(p,&amp;p,0);
							}
						}
					}
				}
			}

			for (i=0;i&lt;256;i++)
			{
				UTF32 src = codeset-&gt;table[i].ucs4;
				UTF32 *src_ptr = &amp;src;
				UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];
				ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
				*dest_ptr = 0;
				codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
			}

			memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
			qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
			list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);
		}
		fclose(fh);
	}
	return 1;
}

/*****************************************************************************/

int codesets_init(void)
{
	int i;
	struct codeset *codeset;
	UTF32 src;

	SM_ENTER;

	list_init(&amp;codesets_list);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 0;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1 + Euro&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European (with EURO)&quot;));
	codeset-&gt;read_only = 1;

	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i==164) src = 0x20AC; /* the EURO sign */
		else src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1;
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-1&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		src = i;
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-2&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Central/East European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_2_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-3&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_3_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-4&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;North European&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_4_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;KOI8-R&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Russian&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0x80) src = i;
		else src = koi8r_to_ucs4[i-0x80];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-5&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Slavic languages&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_5_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-9&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;Turkish&quot;));
	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_9_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-15&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;West European II&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_15_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;ISO-8859-16&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(_(&quot;South-Eastern European&quot;));

	codeset-&gt;read_only = 0;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = iso_8859_16_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;AmigaPL&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amigapl_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	if (!(codeset = (struct codeset*)malloc(sizeof(struct codeset)))) return 1; /* One entry is enough */
	memset(codeset,0,sizeof(*codeset));
	codeset-&gt;name = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;alt_name = NULL;
	codeset-&gt;characterization = mystrdup(&quot;Amiga-1251&quot;);
	codeset-&gt;read_only = 1;
	for (i=0;i&lt;256;i++)
	{
		UTF32 *src_ptr = &amp;src;
		UTF8 *dest_ptr = &amp;codeset-&gt;table[i].utf8[1];

		if (i &lt; 0xa0) src = i;
		else src = amiga1251_to_ucs4[i-0xa0];
		codeset-&gt;table[i].code = i;
		codeset-&gt;table[i].ucs4 = src;
		ConvertUTF32toUTF8(&amp;src_ptr, src_ptr + 1, &amp;dest_ptr, dest_ptr + 6, strictConversion);
		*dest_ptr = 0;
		codeset-&gt;table[i].utf8[0] = (char*)dest_ptr - (char*)&amp;codeset-&gt;table[i].utf8[1];
	}
	memcpy(codeset-&gt;table_sorted,codeset-&gt;table,sizeof(codeset-&gt;table));
	qsort(codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table[0]),(int (*)(const void *arg1, const void *arg2))codesets_cmp_unicode);
	list_insert_tail(&amp;codesets_list,&amp;codeset-&gt;node);

	SM_DEBUGF(15,(&quot;%ld internal charsets\n&quot;,list_length(&amp;codesets_list)));

	{
		/* dynamicaly loaded */

		DIR *dfd; /* directory descriptor */
		struct dirent *dptr; /* dir entry */
		char path[380];

		getcwd(path, sizeof(path));
		if (chdir(SM_CHARSET_DIR) != -1)
		{
			if ((dfd = opendir(SM_CURRENT_DIR)))
			{
				while ((dptr = readdir(dfd)) != NULL)
				{
					if (!strcmp(&quot;.&quot;,dptr-&gt;d_name) || !strcmp(&quot;..&quot;,dptr-&gt;d_name)) continue;
					SM_DEBUGF(15,(&quot;Loading \&quot;%s\&quot; charset\n&quot;,dptr-&gt;d_name,list_length(&amp;codesets_list)));
					codesets_read_table(dptr-&gt;d_name);
				}
				closedir(dfd);
			}
			chdir(path);
		}
	}

	SM_RETURN(1,&quot;%ld&quot;);
}

/*****************************************************************************/

void codesets_cleanup(void)
{
	struct codeset *codeset;

	while ((codeset = (struct codeset*)list_remove_tail(&amp;codesets_list)))
	{
		free(codeset-&gt;name);
		free(codeset-&gt;alt_name);
		free(codeset-&gt;characterization);
		free(codeset);
	}
}

/*****************************************************************************/

struct codeset *codesets_find(const char *name)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);

	/* Return ISO-8859-1 as default codeset */
	if (!name) return codeset;

	while (codeset)
	{
		if (!mystricmp(name,codeset-&gt;name) || !mystricmp(name,codeset-&gt;alt_name)) return codeset;
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}
	return NULL;
}

/*****************************************************************************/

int codesets_unconvertable_chars(struct codeset *codeset, const char *text, int text_len)
{
	struct single_convert conv;
	const char *text_ptr = text;
	int i;
	int errors = 0;

	for (i=0;i &lt; text_len;i++)
	{
		unsigned char c = *text_ptr++;
		if (c)
		{
			int len = trailingBytesForUTF8[c];
			conv.utf8[1] = c;
			strncpy((char*)&amp;conv.utf8[2],text_ptr,len);
			conv.utf8[2+len] = 0;
			text_ptr += len;

			if (!bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode))
				errors++;
		} else break;
	}

	return errors;
}

/*****************************************************************************/

struct codeset *codesets_find_best(const char *text, int text_len, int *error_ptr)
{
	struct codeset *codeset = (struct codeset*)list_first(&amp;codesets_list);
	struct codeset *best_codeset = NULL;
	int best_errors = text_len;

	while (codeset)
	{
		if (!codeset-&gt;read_only)
		{
			int errors = codesets_unconvertable_chars(codeset, text, text_len);

			if (errors &lt; best_errors)
			{
				best_codeset = codeset;
				best_errors = errors;
			}
			if (!best_errors) break;
		}
		codeset = (struct codeset*)node_next(&amp;codeset-&gt;node);
	}

	if (!best_codeset) best_codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (error_ptr) *error_ptr = best_errors;

	return best_codeset;
}

/*****************************************************************************/

int utf8len(const utf8 *str)
{
	int len ;
	unsigned char c;

	if (!str) return 0;
	len = 0;

	while ((c = *str++))
	{
		len++;
		str += trailingBytesForUTF8[c];
	}

	return len;
}

/*****************************************************************************/

utf8 *utf8dup(const utf8 *str)
{
	return (utf8*)mystrdup((char*)str);
}

/*****************************************************************************/

int utf8realpos(const utf8 *str, int pos)
{
	const utf8 *str_save = str;
	unsigned char c;

	if (!str) return 0;

	while (pos &amp;&amp; (c = *str))
	{
		pos--;
		str += trailingBytesForUTF8[c] + 1;
	}
	return str - str_save;
}

/*****************************************************************************/

int utf8charpos(const utf8 *str, int pos)
{
	int cp = 0;
	unsigned char c;

	while (pos &gt; 0 &amp;&amp; (c = *str))
	{
		str += trailingBytesForUTF8[c] + 1;
		pos -= trailingBytesForUTF8[c] + 1;
		cp++;
	}
	return cp;
}

/*****************************************************************************/

int utf8bytes(const utf8 *str)
{
	unsigned char c = *str;
	return trailingBytesForUTF8[c] + 1;
}

/*****************************************************************************/

utf8 *utf8ncpy(utf8 *to, const utf8 *from, int n)
{
	utf8 *saved_to = to;
	for (;n;n--)
	{
		unsigned char c = *from++;
		int len = trailingBytesForUTF8[c];

		*to++ = c;
		for (;len;len--)
		{
			*to++ = *from++;
		}
	}
	return saved_to;
}

/*****************************************************************************/

utf8 *utf8create(const void *from, const char *charset)
{
  /* utf8create_len() will stop on a null byte */
	return utf8create_len(from,charset,0x7fffffff);
}

/*****************************************************************************/

int utf8fromstr(const char *from, struct codeset *codeset, utf8 *dest, unsigned int dest_size)
{
	const char *src = from;
	unsigned char c;
	int conv = 0;

	if (dest_size &lt; 1)
		return 0;

	if (!codeset)
		codeset =  (struct codeset*)list_first(&amp;codesets_list);

	for (src = from;(c = (unsigned char)*src);src++)
	{
		unsigned char *utf8_seq;
		unsigned int l;

		utf8_seq = &amp;codeset-&gt;table[c].utf8[0];

		/* Recall that the first element represents
		 * the number of characters */
		l = utf8_seq[0];
		if (dest_size &lt;= l)
			break;

		utf8_seq++;
		for(;(c = *utf8_seq);utf8_seq++)
			*dest++ = c;

		dest_size -= l;
		conv++;
	}

	*dest = 0;
	return conv;
}

/*****************************************************************************/

utf8 *utf8create_len(const void *from, const char *charset, int from_len)
{
	int dest_size = 0;
	char *dest;
	char *src = (char*)from;
	unsigned char c;
	int len;
	struct codeset *codeset = codesets_find(charset);

	if (!from) return NULL;

	if (!codeset)
	{
		if (!mystricmp(charset,&quot;utf-7&quot;))
		{
			return (utf8*)utf7ntoutf8((char *)from,from_len);
		}
		if (!mystricmp(charset,&quot;utf-8&quot;))
		{
			return (utf8*)mystrdup((char *)from);
		}
		codeset = (struct codeset*)list_first(&amp;codesets_list);
	}

	len = from_len;

	while (((c = *src++) &amp;&amp; (len--)))
		dest_size += codeset-&gt;table[c].utf8[0];

	if ((dest = (char*)malloc(dest_size+1)))
	{
		char *dest_ptr = dest;

		for (src = (char*)from;from_len &amp;&amp; (c = *src);src++,from_len--)
		{
			unsigned char *utf8_seq;

			for(utf8_seq = &amp;codeset-&gt;table[c].utf8[1];(c = *utf8_seq);utf8_seq++)
				*dest_ptr++ = c;
		}

		*dest_ptr = 0;
		return (utf8*)dest;
	}
	return NULL;
}

/*****************************************************************************/

int utf8tostr(const utf8 *str, char *dest, unsigned int dest_size, struct codeset *codeset)
{
	unsigned int i;
	struct single_convert *f;
	char *dest_iter = dest;

	if (!dest_size)
	{
		return 0;
	}

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset || !str)
	{
		*dest = 0;
		return 0;
	}

	for (i=0;i &lt; dest_size-1;i++)
	{
		unsigned char c = *str;
		if (c)
		{
			if (c &gt; 127)
			{
				unsigned int len_add = trailingBytesForUTF8[c];
				unsigned int len_str = len_add + 1;

				BIN_SEARCH(codeset-&gt;table_sorted,0,255,mystrncmp((unsigned char*)str,codeset-&gt;table_sorted[m].utf8+1,len_str),f);

				if (f) *dest_iter++ = f-&gt;code;
				else *dest_iter++ = '_';

				str += len_add;
			} else *dest_iter++ = c;

			str++;
		} else break;
	}
	*dest_iter = 0;
	return i;
}

/*****************************************************************************/

char *utf8tostrcreate(const utf8 *str, struct codeset *codeset)
{
	char *dest;
	int len;
	if (!str) return NULL;
	len = strlen((char*)str);
	if ((dest = (char*)malloc(len+1)))
		utf8tostr(str,dest,len+1,codeset);
	return dest;
}

/*****************************************************************************/

int utf8tochar(const utf8 *str, unsigned int *chr, struct codeset *codeset)
{
	struct single_convert conv;
	struct single_convert *f;
	unsigned char c;
	int len = 0;

	if (!codeset) codeset = (struct codeset*)list_first(&amp;codesets_list);
	if (!codeset) return 0;

	if ((c = *str++))
	{
		int i;

		len = trailingBytesForUTF8[c];
		conv.utf8[1] = c;

		for (i=0;i&lt;len;i++)
		{
			if (!(conv.utf8[i+2] = *str++))
			{
				/* We encountered a 0 byte although the trailing byte suggested
				 * a different length. Hence the given utf8 sequence is not
				 * considered as valid */
				*chr = 0;
				return i+1;
			}
		}
		conv.utf8[2+len] = 0;

		if ((f = (struct single_convert*)bsearch(&amp;conv,codeset-&gt;table_sorted,256,sizeof(codeset-&gt;table_sorted[0]),codesets_cmp_unicode)))
		{
			*chr = f-&gt;code;
		} else *chr = 0;
	} else *chr = 0;
	return len+1;
}

/*****************************************************************************/

static inline int utf8cmp_single(unsigned char *a, unsigned char *b)
{
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
	int d;

	if ((d = a[0] - b[0])) return d;
	if ((d = a[1] - b[1])) return d;
	if ((d = a[2] - b[2])) return d;
	if ((d = a[3] - b[3])) return d;
	return 0;
#else
	return (*((unsigned int *)a) - *((unsigned int *)b));
#endif
}

/*****************************************************************************/

int utf8tolower(const char *str, char *dest)
{
	unsigned char ch[4] = {0,0,0,0};
	unsigned char c;
	struct uniconv *uc;
	int bytes;
	int i;

	c = *str++;
	if (c&lt;0x80)
	{
		*dest = tolower(c);
		return 1;
	}
	bytes = trailingBytesForUTF8[c];
	if (bytes &gt; 3)
	{
		*dest++ = c;
		memcpy(dest + 1,str + 1,bytes);
		return bytes + 1;
	}

	ch[3-bytes] = c;
	for (i=bytes-1;i&gt;=0;i--)
	{
		if (!(ch[3-i] = *str++))
			return 0;
	}

	BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),utf8cmp_single(utf8_tolower_table[m].from, ch),uc);

	if (uc)
		memcpy(dest, uc-&gt;to + 3 - bytes, bytes + 1);
	else
		memcpy(dest, ch + 3 - bytes, bytes + 1);
	return bytes + 1;
}

/*****************************************************************************/

int utf8stricmp(const char *str1, const char *str2)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (1)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8stricmp_len(const char *str1, const char *str2, int len)
{
	unsigned char c1;
	unsigned char c2;

	if (!str1)
	{
		if (!str2) return 0;
		return -1;
	}

	if (!str2) return 1;

	while (len&gt;0)
	{
		int d;
		char bytes1,bytes2;

		c1 = *str1++;
		c2 = *str2++;
		len--;

		if (!c1)
		{
			if (!c2) return 0;
			return -1;
		}
		if (!c2) return 1;

		if (c1 &lt; 0x80)
		{
			if (c2 &lt; 0x80)
			{
				d = tolower(c1) - tolower(c2);
				if (d) return d;
				continue;
			} else
			{
				/* TODO: must use locale sensitive sorting */
				return -1;
			}
		}
		if (c2 &lt; 0x80) return 1; /* TODO: must use locale sensitive sorting */

		bytes1 = trailingBytesForUTF8[c1];
		bytes2 = trailingBytesForUTF8[c2];

		/* case mapping only happens within same number of bytes (currently) */
		if ((d = bytes1 - bytes2)) return d;

		if (bytes1 &gt; 3)
		{
			/* case mapping relevant characters are only withing 4 bytes */
			while (bytes1)
			{
				if ((d = *str1++ - *str2++)) return d;
				bytes1--;
			}
		} else
		{

			unsigned char ch1[4],ch2[4];
			struct uniconv *uc1;
			struct uniconv *uc2;
			int ch1l;
			int ch2l;

			*((unsigned int *)ch1) = 0;
			*((unsigned int *)ch2) = 0;

			ch1[3-bytes1] = c1;
			ch2[3-bytes1] = c2;

			while (bytes1)
			{
				bytes1--;
				ch1[3 - bytes1] = *str1++;
				ch2[3 - bytes1] = *str2++;

				len--;
			}


			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch1)),uc1);
			BIN_SEARCH(utf8_tolower_table,0,ARRAY_LEN(utf8_tolower_table),(*((unsigned int *)utf8_tolower_table[m].from) - *((unsigned int *)ch2)),uc2);

			if (uc1) ch1l = *((unsigned int *)uc1-&gt;to);
			else ch1l = *((unsigned int *)ch1);

			if (uc2) ch2l = *((unsigned int *)uc2-&gt;to);
			else ch2l = *((unsigned int *)ch2);

			if (ch1l != ch2l)
			{
				if (ch1l &lt; ch2l) return -1;
				return 1;
			}
		}
	}
	return 0;
}

/*****************************************************************************/

int utf8match(const char *haystack, const char *needle, int case_insensitive, match_mask_t *match_mask)
{
	int h, n;
	int needle_len;
	int haystack_len;

	unsigned char hc;
	unsigned char nc;

	haystack_len = strlen(haystack);
	needle_len = strlen(needle);

	h = 0;
	n = 0;
	while (h &lt; haystack_len &amp;&amp; n &lt; needle_len)
	{
		int match;
		int hbytes;
		int nbytes;

		match = 0;
		hc = haystack[h];
		nc = needle[n];

		hbytes = trailingBytesForUTF8[hc];
		nbytes = trailingBytesForUTF8[nc];

		if (hbytes == nbytes)
		{
			if (hc == nc)
			{
				int i;

				match = 1;

				for (i=0; i &lt; hbytes; i++)
				{
					if (haystack[i+1] != needle[i+1])
						match = 0;
				}
			} else
			{
				if (hbytes == 0 &amp;&amp; case_insensitive)
				{
					if (tolower(hc) == tolower(nc))
					{
						match = 1;
					}
				}
			}

			if (!match &amp;&amp; case_insensitive &amp;&amp; hbytes &gt; 0)
			{
				char hchars[6] = {0};
				char nchars[6] = {0};
				int hl, nl;

				if ((hl = utf8tolower(&amp;haystack[h], hchars)) &gt; 0 &amp;&amp;
					(nl = utf8tolower(&amp;needle[n], nchars)) &gt; 0)
				{
					if (hl == nl)
					{
						match = memcmp(hchars, nchars, nl) == 0;
					}
				}

			}
		}

		if (match)
		{
			n += nbytes + 1;
		}

		if (match_mask)
		{
			unsigned int match_pos;

			match_pos = match_bitmask_pos(h);
			if (match)
			{
				match_mask[match_pos] |= match_bitmask(h);
			} else
			{
				match_mask[match_pos] &amp;= ~match_bitmask(h);
			}
		}

		h += hbytes + 1;
	}

	if (n == needle_len)
	{
		if (match_mask)
		{
			/* Make sure that the remaining relevant positions are cleared */
			for (;h &lt; haystack_len; h++)
			{
				match_mask[match_bitmask_pos(h)] &amp;= ~match_bitmask(h);
			}
		}
		return 1;
	}
	return 0;
}

/*****************************************************************************/

char *utf8stristr(const char *str1, const char *str2)
{
	int str2_len;

	if (!str1 || !str2) return NULL;

	str2_len = strlen(str2);

	while (*str1)
	{
		if (!utf8stricmp_len(str1,str2,str2_len))
			return (char*)str1;
		str1++;
	}
	return NULL;
}

/*****************************************************************************/

const char *uft8toucs(const char *chr, unsigned int *code)
{
	unsigned char c = *chr++;
	unsigned int ucs = 0;
	int i,bytes;
	if (!(c &amp; 0x80))
	{
		*code = c;
		return chr;
	} else
	{
		if (!(c &amp; 0x20))
		{
			bytes = 2;
			ucs = c &amp; 0x1f;
		}
		else if (!(c &amp; 0x10))
		{
			bytes = 3;
			ucs = c &amp; 0xf;
		}
		else if (!(c &amp; 0x08))
		{
			bytes = 4;
			ucs = c &amp; 0x7;
		}
		else if (!(c &amp; 0x04))
		{
			bytes = 5;
			ucs = c &amp; 0x3;
		}
		else /* if (!(c &amp; 0x02)) */
		{
			bytes = 6;
			ucs = c &amp; 0x1;
		}

		for (i=1;i&lt;bytes;i++)
			ucs = (ucs &lt;&lt; 6) | ((*chr++)&amp;0x3f);
	}
	*code = ucs;
	return chr;
}

static unsigned char base64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/&quot;;
static short invbase64[128];

static unsigned char ibase64[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,&quot;;
static short iinvbase64[128];

static unsigned char direct[] = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'(),-./:?&quot;;
static unsigned char optional[] = &quot;!\&quot;#$%&amp;*;&lt;=&gt;@[]^_`{|}&quot;;
static unsigned char spaces[] = &quot; \011\015\012&quot;;		/* space, tab, return, line feed */
static char mustshiftsafe[128];
static char mustshiftopt[128];

static int needtables = 1;

static void tabinit(void)
{
	int i, limit;

	for (i = 0; i &lt; 128; ++i)
	{
		mustshiftopt[i] = mustshiftsafe[i] = 1;
		invbase64[i] = -1;
	}
	limit = strlen((char*)direct);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[direct[i]] = mustshiftsafe[direct[i]] = 0;
	limit = strlen((char*)spaces);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[spaces[i]] = mustshiftsafe[spaces[i]] = 0;
	limit = strlen((char*)optional);
	for (i = 0; i &lt; limit; ++i)
		mustshiftopt[optional[i]] = 0;
	limit = strlen((char*)base64);
	for (i = 0; i &lt; limit; ++i)
		invbase64[base64[i]] = i;

	/* that's for the modified imap utf7 stuff */
	limit = strlen((char*)ibase64);
	for (i = 0; i &lt; limit; ++i)
		iinvbase64[ibase64[i]] = i;

	needtables = 0;
}

#if __cplusplus &gt;= 201703L
#define DECLARE_BIT_BUFFER unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#else
#define DECLARE_BIT_BUFFER register unsigned long BITbuffer = 0, buffertemp = 0; int bufferbits = 0
#endif

#define BITS_IN_BUFFER bufferbits
#define WRITE_N_BITS(x, n) ((BITbuffer |= ( ((x) &amp; ~(-1L&lt;&lt;(n))) &lt;&lt; (32-(n)-bufferbits) ) ), bufferbits += (n) )
#define READ_N_BITS(n) ((buffertemp = (BITbuffer &gt;&gt; (32-(n)))), (BITbuffer &lt;&lt;= (n)), (bufferbits -= (n)), buffertemp)

/*****************************************************************************/

char *utf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '+' || c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('+',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '+')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8toiutf7(char *utf8, int sourcelen)
{
	FILE *fh;
	char *dest = NULL;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;
		int shifted = 0;
		DECLARE_BIT_BUFFER;

		while (1)
		{
			unsigned char c;
			int noshift;

			if (sourcelen)
			{
				c = *utf8;
				noshift = (c &gt;= 0x20 &amp;&amp; c &lt;= 0x7e) &amp;&amp; (c != '&amp;');
			} else
			{
				c = 0;
				noshift = 1;
			}

			if (shifted)
			{
				while (BITS_IN_BUFFER &gt;= 6)
				{
					unsigned char bits = READ_N_BITS(6);
					fputc(ibase64[bits],fh);
				}

				if (noshift)
				{
					int bits_in_buf = BITS_IN_BUFFER;

					if (bits_in_buf)
					{
						unsigned char bits = READ_N_BITS(bits_in_buf);
						bits &lt;&lt;= 6 - bits_in_buf;
						fputc(ibase64[bits],fh);
					}
					shifted = 0;
					fputc('-',fh);
				}
			}

			if (!c) break;

			if (noshift)
			{
				if (c == '&amp;')
				{
					fputs(&quot;&amp;-&quot;,fh);
				} else fputc(c,fh);
				utf8++;
				sourcelen--;
			} else
			{
				UTF8 *source = (UTF8*)utf8;
				UTF16 dest = 0;
				UTF16 *dest_ptr = &amp;dest;
				ConversionResult res;

				res = ConvertUTF8toUTF16(&amp;source, source + sourcelen, &amp;dest_ptr, dest_ptr + 1, strictConversion);
				if (res == conversionOK || res == targetExhausted)
				{
					sourcelen -= trailingBytesForUTF8[c] + 1;
					utf8 += trailingBytesForUTF8[c] + 1;

					if (!shifted)
					{
						fputc('&amp;',fh);
						shifted = 1;
					}

					WRITE_N_BITS(dest,16);
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}
	return dest;
}

/*****************************************************************************/

char *iutf7ntoutf8(char *source, int sourcelen)
{
	FILE *fh;
	int base64value=0,base64EOF=0,first=0;
	int shifted = 0;
	char *dest = NULL;
	DECLARE_BIT_BUFFER;

	if (needtables) tabinit();

	if ((fh = tmpfile()))
	{
		int dest_len;

		while (sourcelen)
		{
			unsigned char c = *source++;
			sourcelen--;

			if (shifted)
			{
				if ((base64EOF = (!sourcelen) || (c &gt; 0x7f) || (base64value = invbase64[c]) &lt; 0))
				{
					shifted = 0;
					/* If the character causing us to drop out was SHIFT_IN or
					   SHIFT_OUT, it may be a special escape for SHIFT_IN. The
					   test for SHIFT_IN is not necessary, but allows an alternate
					   form of UTF-7 where SHIFT_IN is escaped by SHIFT_IN. This
					   only works for some values of SHIFT_IN.
					 */
					if (c &amp;&amp; sourcelen &amp;&amp; (c == '-'))
					{
						/* get another character c */
						unsigned char prevc = c;

						c = *source++;

						/* If no base64 characters were encountered, and the
							 character terminating the shift sequence was
							 SHIFT_OUT, then it's a special escape for SHIFT_IN.
						*/
						if (first &amp;&amp; prevc == '-')
						{
							fputc('&amp;',fh);
						}
					}
				} else
				{
					/* Add another 6 bits of base64 to the bit buffer. */
					WRITE_N_BITS(base64value, 6);
					first = 0;
				}
			}

			/* Extract as many full 16 bit characters as possible from the
			   bit buffer.
			 */
			while (BITS_IN_BUFFER &gt;= 16)
			{
				UTF32 src_utf32 = READ_N_BITS(16);
				UTF32 *src_utf32_ptr = &amp;src_utf32;
				UTF8 target_utf8[10];
				UTF8 *target_utf8_ptr = target_utf8;

				ConvertUTF32toUTF8(&amp;src_utf32_ptr,src_utf32_ptr+1,&amp;target_utf8_ptr,target_utf8+10, strictConversion);

				fwrite(target_utf8,1,target_utf8_ptr - target_utf8,fh);
			}

			if (!c) break;

			if (base64EOF) BITS_IN_BUFFER = 0;

			if (!shifted)
			{
				if (c == '&amp;')
				{
					shifted = first = 1;
				} else
				{
					if (c &lt;= 0x7f)
					{
						fputc(c,fh);
					} /* else the source is invalid, so we ignore this */
				}
			}
		}

		if ((dest_len = ftell(fh)))
		{
	    fseek(fh,0,SEEK_SET);
			if ((dest = (char*)malloc(dest_len+1)))
			{
				fread(dest,1,dest_len,fh);
				dest[dest_len]=0;
			}
		}
	}

	return dest;
}

/*****************************************************************************/

char *utf8topunycode(const utf8 *source, int sourcelen)
{
	enum punycode_status status;
	const utf8 *sourceend;
	char *puny;
	punycode_uint puny_len;

	punycode_uint *dest, *target;
	punycode_uint dest_len;

	if (!(dest = (punycode_uint *)malloc(sourcelen * sizeof(punycode_uint))))
		return NULL;

	target = dest;
	sourceend = source + sourcelen;

	while (source &lt; sourceend)
	{
		punycode_uint ch = 0;
		unsigned short extraBytesToRead = trailingBytesForUTF8[*(UTF8*)source];

		if (source + extraBytesToRead &gt;= sourceend)
		{
			/* source exhausted */
			free(dest);
			return NULL;
		}

		/* Do this check whether lenient or strict */
		if (!isLegalUTF8((UTF8*)source, extraBytesToRead+1))
		{
			free(dest);
			return NULL;
		}

		/*
		 * The cases all fall through.
		 */
		switch (extraBytesToRead) {
			case 3:	ch += *source++; ch &lt;&lt;= 6;
			case 2:	ch += *source++; ch &lt;&lt;= 6;
			case 1:	ch += *source++; ch &lt;&lt;= 6;
			case 0:	ch += *source++;
		}
		ch -= offsetsFromUTF8[extraBytesToRead];

		if (ch &lt;= UNI_MAX_UTF32) {
			*target++ = ch;
		} else if (ch &gt; UNI_MAX_UTF32) {
			*target++ = UNI_REPLACEMENT_CHAR;
		}
	}

	dest_len = target - dest; /* No 0 ending */
	puny_len = dest_len * 2;

	do
	{
		int strored_puny_len = puny_len;

		if (!(puny = (char*)malloc(puny_len+5)))
		{
			free(dest);
			return NULL;
		}
		status = punycode_encode(dest_len, dest, NULL /* case flags */, &amp;puny_len, puny);

		if (status == punycode_success)
		{
			puny[puny_len] = 0;
			free(dest);
			return puny;
		}
		puny_len = strored_puny_len * 2;
	} while (status == punycode_big_output);

	free(puny);
	free(dest);
	return NULL;
}
/*****************************************************************************/

utf8 *punycodetoutf8(const char *source, int sourcelen)
{
	enum punycode_status status;
	punycode_uint *utf32;
	punycode_uint length;

	length = sourcelen;

	if (!(utf32 = (punycode_uint*)malloc(sizeof(punycode_uint)*sourcelen)))
		return NULL;

	status = punycode_decode(sourcelen, source, &amp;length, utf32, NULL);
	if (status == punycode_success)
	{
		utf8 *dest = (utf8*)malloc(sourcelen * 4);
		if (dest)
		{
			UTF8 *dest_start = (UTF8*)dest;
			UTF32 *source_start = (UTF32*)utf32;

			ConvertUTF32toUTF8((UTF32**)&amp;source_start, (UTF32*)(utf32) + length, &amp;dest_start, dest_start + sourcelen * 4 - 2, strictConversion);
			*dest_start = 0;
			free(utf32);
			return dest;
		}
	}
	free(utf32);
	return NULL;
}

/*****************************************************************************/

int isascii7(const char *str)
{
	char c;
	if (!str) return 1;
	while ((c = *str++))
	{
		if (c &amp; 0x80) return 0;
	}
	return 1;
}
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;

&lt;syntaxhighlight lang=&quot;c&quot;&gt;
&lt;/syntaxhighlight&gt;


== Library Calls ==

&lt;pre&gt;
TABLE OF CONTENTS

codesets.library/codesets.library
codesets.library/CodesetsSupportedA
codesets.library/CodesetsFindA
codesets.library/CodesetsFindBestA
codesets.library/CodesetsConvertStrA
codesets.library/CodesetsFreeA
codesets.library/CodesetsFreeVecPooledA
codesets.library/CodesetsSetDefaultA
codesets.library/CodesetsListCreateA
codesets.library/CodesetsListDeleteA
codesets.library/CodesetsListAddA
codesets.library/CodesetsListRemoveA
codesets.library/CodesetsUTF8CreateA
codesets.library/CodesetsUTF8ToStrA
codesets.library/CodesetsUTF8Len
codesets.library/CodesetsIsValidUTF8
codesets.library/CodesetsIsLegalUTF8
codesets.library/CodesetsIsLegalUTF8Sequence
codesets.library/CodesetsStrLenA
codesets.library/CodesetsConvertUTF16toUTF32
codesets.library/CodesetsConvertUTF16toUTF8
codesets.library/CodesetsConvertUTF32toUTF16
codesets.library/CodesetsConvertUTF32toUTF8
codesets.library/CodesetsConvertUTF8toUTF16
codesets.library/CodesetsConvertUTF8toUTF32
codesets.library/CodesetsDecodeB64A
codesets.library/CodesetsEncodeB64A


codesets.library/codesets.library

    *******************************************************************
    Copyright (c) 2005-2008 by codesets.library Open Source Team
    $Id$
    $URL$

    codesets.library is an AmigaOS shared library which provides
    functions to deal with different kind of codesets. It provides
    general character conversion routines, e.g. for converting
    from one charset (e.g. UTF8) into another (e.g. ISO-8859-1) or
    vice versa.

    codesets.library is mainly based on some code from UNICODE, some
    code from the SimpleMail project as well as some additions done
    by the codesets.library Open Source Team.

    It is released and distributed under the terms of the GNU Lesser
    General Public License (LGPL) and available free of charge.

    Please visit http://www.sf.net/projects/codesetslib/ for
    the very latest version and information regarding codesets.library.
    *******************************************************************

    For some short introduction on how to use codesets.library, the
    following pharagraph should provide a good summary. What you
    usually want to do with codesets.library is, to convert strings from
    one so-called &quot;Source Codeset&quot; into another &quot;Destination Codeset&quot;.
    The following list are only the main functions provided to
    developers, wanting to achieve this conversion in their applications:


    CodesetsSupportedA()
    --------------------

      For querying codesets library which codesets/charsets it supports
      either by its internal available charsets or by having obtained
      them from the operating system (e.g. AmigaOS4), this function
      can be used.

      E.g. in a MUI application you would do something like:

      -- cut here --
      STRPTR *array;

      if((array = CodesetsSupportedA(NULL)))
      {
        DoMethod(list, MUIM_List_Insert, array, -1, MUIV_List_Insert_Sorted);
        CodesetsFreeA(array, NULL);
      }
      -- cut here --


    CodesetsFindA()
    ---------------

      For processing/converting a specific string, you normally have to
      specify in which codeset this string has to be intepreted. For this
      purpose you have to pass a so-called &quot;Source Codeset&quot; to the main
      function of codesets.library. With the &quot;CodesetsFindA()&quot; function you
      can query codesets.library for providing you a pointer to the
      corresponding codeset structure which you afterwards will forward to
      the main conversion routines later on.

      For receiving the pointer to the Amiga-1251 codeset:
      -- cut here --
      struct codeset *cs;

      if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                            CSA_FallbackToDefault, FALSE,
                            TAG_DONE)))
      {
        ...
      }
      -- cut here --

      For querying codesets.library for the currently used system wide
      default of your running operating system:
      -- cut here --
      struct codeset *default;

      if((default = CodesetsFindA(NULL, NULL)))
      {
        ...
      }
      -- cut here --


    CodesetsConvertStrA()
    ---------------------

      The more or less most common function to use in codesets.library is
      definitly this function. It allows to convert a string from
      one &quot;Source Codeset&quot; to another &quot;Destination Codeset&quot;. It takes
      the source string converts it internally into UTF8 if necessary and
      then directly convert the UTF8 to the specified destination codeset.

      To convert a string 'str' to a destination codeset:
      -- cut here --
      STRPTR destString;

      if((destString = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                          CSA_DestCodeset,   destCodeset,
                                          CSA_Source,        str,
                                          TAG_DONE)))
      {
        ....

        CodesetsFreeA(destString, NULL);
      }
      -- cut here --

   Even if the above functions should cover most of the common functionality
   an ordinary user of codesets.library would require, it supplies a lot more
   functions which in fact we will not go into detail here but present
   certain examples in the respective documentation section of each function.

   However, if you find the documentation is still too limited or you feel
   some major functionality is missing regarding dealing with codesets,
   please let us know so that we or even you can improve it.


   Your codesets.library Open Source Team.
   February 2006


codesets.library/CodesetsSupportedA

   NAME
    CodesetsSupportedA - returns names of supported codesets

   SYNOPSIS
    array = CodesetsSupportedA(attrs);
                               A0

    STRPTR * CodesetsSupportedA(struct TagItem *);

    array = CodesetsSupported(tag1, ...);
                              A0

    STRPTR * CodesetsSupported(Tag, ...);

   FUNCTION
    Returns a NULL terminated array of the supported codeset
    names. The array _must_ be freed with CodesetsFreeA().

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

     CSA_AllowMultibyteCodesets (BOOL)
       Include multibyte codesets (UTF8, UTF16, UTF32) in the
       generated names array.
       Default: TRUE

   RESULT
    array - the names array or NULL on an error.

   EXAMPLE
    For printing out all supported codeset names:

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      int i;

      for(i=0; array[i] != NULL; i++)
        printf(&quot;%s&quot;, array[i]);

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindA

   NAME
    CodesetsFindA - finds a codeset

   SYNOPSIS
    codeset = CodesetsFindA(name, attrs);
    D0                      A0    A1

    struct codeset * CodesetsFindA(STRPTR, struct TagItem *);

    codeset = CodesetsFind(name, tag1, ...);
    D0                     A0    A1

    struct codeset * CodesetsFind(STRPTR, Tag, ...);

   FUNCTION
    Finds and returns a codeset by its name. The data behind the
    pointer should be considered read-only and must not be altered
    in any way.

   INPUTS
    name - the codeset name (or alias) to find
    attrs - a list of additional tag items. Valid items are:

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied codeset name can't be found.
        Default: TRUE

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

   RESULT
    codeset - the codeset or NULL on an error

   EXAMPLE
     E.g. for receiving the pointer to the Amiga-1251 codeset:

     -- cut here --
     struct codeset *cs;

     if((cs = CodesetsFind(&quot;Amiga-1251&quot;,
                           CSA_FallbackToDefault, FALSE,
                           TAG_DONE)))
     {
       ...
     }
     -- cut here --

     For querying codesets.library for the currently used system
     wide default of your running operating system:
     -- cut here --
     struct codeset *default;

     if((default = CodesetsFindA(NULL, NULL)))
     {
       ...
     }
     -- cut here --

   NOTE
    Please note for querying the system's default codeset the
    method of finding this codeset is highly dependent on the way
    the operating system can be queried for it. E.g. on AmigaOS4
    the default codeset is queried with updated system functions,
    but for AmigaOS3 a static list of language&lt;&gt;codeset mappings
    is used.

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsFindBestA

   NAME
    CodesetsFindBestA - finds the best codeset matching a
                        string content.

   SYNOPSIS
    codeset = CodesetsFindBestA(attrs);
    D0                          A0

    struct codeset * CodesetsFindBestA(struct TagItem *);

    codeset = CodesetsFindBest(tag1, ...);
    D0                         A0

    struct codeset * CodesetsFindBest(Tag, ...);

   FUNCTION
    Returns the best found codeset for the given text in the supplied
    codeset family. In case no proper codeset for the supplied source string
    could be found, NULL is returned or the default codeset if the
    CSA_FallbackToDefault attribute is set to TRUE. In addition, in case
    the CSA_ErrPtr is given, the amount of failed identifications (chars)
    are returned.

   INPUTS
    attrs - a list of tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to check just a part
        Default: string length of CSA_Source

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found errors (not identifyable chars)
        Default: NULL

      CSA_CodesetList (struct codesetList *)
        You may supply an unlimited number of additional
        codeset lists which you have previously allocated/loaded
        with CodesetsListCreateA(). Otherwise just the internal
        list of available codesets will be searched.
        Default: NONE

      CSA_CodesetFamily (ULONG)
        To narrow the analyze, a user might define the codeset family
        of which the supplied text might be composed of. The reason for
        this is, that there isn't a unique identification algorithm
        which can tell the codeset out of a given text. So to narrow
        the identification, the follow values might be specified:

          CSV_CodesetFamily_Latin    - Latin codeset family (e.g. ISO-8859-X)
          CSV_CodesetFamily_Cyrillic - Cyrillic codeset family (e.g. KOI8R)

        Default: CSV_CodesetFamily_Latin

      CSA_FallbackToDefault (BOOL)
        If TRUE the function never fails and returns the default
        codeset if the supplied text couldn't be identified
        Default: FALSE

   RESULT
    codeset - the best matching codeset or NULL in case a NULL pointer
              was supplied as the source string.

   EXAMPLE
     E.g. for receiving the pointer to 'best matching' codeset matching
     a KOI8-R string:

     -- cut here --
     struct codeset *cs;
     char str[] = &quot;îÅ×ÏÚÍÏÖÎÏ ÐÅÒÅËÏÄÉÒÏ×ÁÔØ ÉÚ ËÏÄÉÒÏ×ËÉ&quot;;
     int errPtr;

     if((cs = CodesetsFindBest(CSA_Source, str,
                               CSA_ErrPtr, &amp;errPtr,
                               CSA_CodesetFamily, CSV_CodesetFamily_Cyrillic,
                               CSA_FallBackToDefault, FALSE,
                               TAG_DONE)))
     {
       ... should return the KOI8-R codeset ...
     }
     -- cut here --

   SEE ALSO
    codesets.library/CodesetsListCreateA


codesets.library/CodesetsConvertStrA

   NAME
    CodesetsConvertStrA - converts a string from one source codeset to
                          another destination codeset.

   SYNOPSIS
    dest = CodesetsConvertStrA(attrs)
    D0                         A0

    STRPTR CodesetsConvertStrA(struct TagItem *);

    dest = CodesetsConvertStr(tag1, ...);
    D0                        A0

    STRPTR CodesetsConvertStr(Tag, ...);

   FUNCTION
    The function takes source string which is encoded in a so-called
    'Source codeset' and converts it immediately into an equivalent
    string which will be encoded in the corresponding 'Destination Codeset'.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_DestCodeset (struct codeset *)
        The codeset to which the source string should be converted to.
        Default: the system's default codeset

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string
        which is returned.

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    either a pointer to the generated destination string or NULL
    on a found error.

   EXAMPLE
    To convert an ISO-8859-1 encoded string 'src' into an Amiga-1251
    equivalent 'dst' string:
    -- cut here --
    STRPTR src, dst;
    struct codeset *srcCodeset, *dstCodeset;

    srcCodeset = CodesetsFindA(&quot;ISO-8859-1&quot;, NULL);
    dstCodeset = CodesetsFindA(&quot;Amiga-1251&quot;, NULL);

    if((dst = CodesetsConvertStr(CSA_SourceCodeset, srcCodeset,
                                 CSA_DestCodeset,   dstCodeset,
                                 CSA_Source,        src,
                                 TAG_DONE)))
    {
      ....

      CodesetsFreeA(dst, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsFreeA


codesets.library/CodesetsFreeA

   NAME
    CodesetsFreeA - frees objects previously internally allocated
                    by codesets.library

   SYNOPSIS
    CodesetsFreeA(obj, attrs)
                  A0   A1
    void CodesetsFreeA(APTR, struct TagItem *);

    CodesetsFree(obj, tag1, ...);
                 A0   A1
    void CodesetsFree(APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library. E.g. using
    functions like CodesetsSupportedA() or CodesetsConvertStrA().

   INPUTS
    obj - the object to free
    attrs - a list of additional tag items. Currently non items.

   RESULT
    no result

   EXAMPLE

    -- cut here --
    STRPTR *array;

    if((array = CodesetsSupportedA(NULL)))
    {
      ...

      CodesetsFreeA(array, NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsSupportedA
    codesets.library/CodesetsConvertStrA


codesets.library/CodesetsFreeVecPooledA

   NAME
    CodesetsFreeVecPooledA - frees objects previously allocated
                             by methods supporting CSA_Pool

   SYNOPSIS
    CodesetsFreeVecPooledA(pool, obj, attrs)
                           A0    A1   A2
    void CodesetsFreeVecPooledA(APTR, APTR, struct TagItem *);

    CodesetsFreeVecPooled(pool, obj, tag1, ...);
                          A0    A1   A2
    void CodesetsFreeVecPooled(APTR, APTR, Tag, ...);

   FUNCTION
    Frees object previously allocated by codesets.library via a
    private memory pool which was previously used on codesets
    functions via the CSA_Pool tag.

   INPUTS
    pool - pointer to the private memory pool
    obj - the object to free
    attrs - a list of additional tag items. Valid tags are:

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    no result

   EXAMPLE

    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsSetDefaultA

   NAME
    CodesetsSetDefaultA - sets the default codeset, overwriting
                          the system default if necessary.

   SYNOPSIS
    codeset = CodesetsSetDefaultA(name, attrs);
                                  A0    A1

    struct codeset * CodesetsSetDefaultA(STRPTR, struct TagItem *);

    codeset = CodesetsSetDefault(name, tag1, ...);
                                 A0    A1

    struct codeset * CodesetsSetDefault(STRPTR, Tag, ...);

   FUNCTION
    Sets the default codeset to name. The codeset will be stored in
    the environment variable 'codeset_default'.

   INPUTS
    name - the name of the codeset to set as default
    attrs - a list of additional tag items. Valid items are:

      CSA_Save (BOOL)
        If TRUE the codeset will be permanently saved and survives
        a reset. Otherwise the default setting will just last until
        the next reboot.
        Default: FALSE

   RESULT
    codeset - the codeset or NULL

   NOTE
    In case the operating system supports the direct query of the
    currently active system's default codeset, this function will
    still overwrite this setting. So by using this method a user may
    overwrite all system's setting and set a global default codeset
    for his machine no matter what the OS suggests. However, in case
    your operating sytsem perfectly supports the querying of the
    system's default codeset (e.g. AmigaOS4) you are adviced to use
    this function with care - or even avoid to use it at all.

   SEE ALSO
    codesets.library/CodesetsFindA


codesets.library/CodesetsListCreateA

   NAME
    CodesetsListCreateA - creates a private, task-wise codeset list
                          and returns it to the user for further reference.

   SYNOPSIS
    list = CodesetsListCreateA(attrs);
    D0                         A0

    struct codesetList * CodesetsListCreateA(struct TagItem *);

    list = CodesetsListCreate(tag1, ...);
    D0                        A0

    struct codesetList * CodesetsListCreateA(Tag, ...);

   FUNCTION
    This function allows to create a private, task-wise codeset list by
    loading charset files from either a whole directory tree, a specific
    charset file or even by using an existing codeset structure.
    By using this function, an application might load and carry its very
    own private charsets in parallel to the internal charsets of
    codeset.library. This way each application can provide a different
    codeset list to the user without having to load and manage these
    lists on their own.

   INPUTS
    attrs - a list of additional tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    list - the private codeset list or NULL on an error condition

   NOTE
    For convienence, if no tag item attribute at all is supplied to the
    function, codesets.library will try to load charsets from the
    corresponding &quot;PROGDIR:Charsets&quot; directoy and add found codeset to
    the list. However, in case a tag item is specified (no matter what
    kind) the PROGDIR: scanning will be omitted.

   EXAMPLE
    For loading all found charset files from PROGDIR:Charsets:

    -- cut here --
    struct codesetList *csList;

    if((csList = CodesetsListCreateA(NULL)))
    {
      STRPTR codesetArray = CodesetsSupported(CSA_CodesetList, csList,
                                              TAG_DONE);

      // codesetsArray should now also carry our private
      // codesets from PROGDIR:Charsets
      ...

      CodesetsListDeleteA(CSA_CodesetList, csList,
                          TAG_DONE);
    }
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA
    codesets.library/CodesetsListSupportedA
    codesets.library/CodesetsListFindA
    codesets.library/CodesetsListFindBestA


codesets.library/CodesetsListDeleteA

   NAME
    CodesetsListDeleteA - deletes/frees all resources of previously created
                          private codeset lists.

   SYNOPSIS
    result = CodesetsListDeleteA(attrs);
    D0                           A0

    BOOL CodesetsListDeleteA(struct TagItem *);

    result = CodesetsListDelete(tag1, ...);
    D0                          A0

    BOOL CodesetsListDelete(Tag, ...);

   FUNCTION
    This function deletes all resources (also the contained codeset
    structures per default) and frees the memory of previously allocated
    private codeset lists.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetList (struct codesetList *)
        Pointer to a previously created, private codeset list whos
        resources should be freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all contained codesets should also be freed/deleted,
        otherwise just frees the list object itself.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Please note that if you added an explicit codeset structure to more
    than two private codeset lists you may run into problems with you
    don't take care of this yourself. This is a dumb function which just
    walks through the list and frees all resources. Set CSA_FreeCodesets
    to FALSE in case you just want to free the list object.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListAddA
    codesets.library/CodesetsListRemoveA


codesets.library/CodesetsListAddA

   NAME
    CodesetsListAddA - allows to add additional codesets to an already
                       existing private codeset list previously created with
                       CodesetsListCreateA().

   SYNOPSIS
    result = CodesetsListAddA(attrs);
    D0                        A0

    BOOL CodesetsListAddA(struct TagItem *);

    result = CodesetsListAdd(tag1, ...);
    D0                       A0

    BOOL CodesetsListAdd(Tag, ...);

   FUNCTION
    This function allows to add additional codesets to an already existing
    private codeset list. Either codesets themself may be added directly, or
    the path to either a file or a directory may be specified from which
    additional codesets may be loaded from known charset files.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_CodesetDir (STRPTR)
        The path to a whole directory which codesets library will
        walk through for searching for proper charset files.
        Default: NULL

      CSA_CodesetFile (STRPTR)
        The path to a specific file which codesets.library will try
        to load as a standard charset translation file.
        Default: NULL

      CSA_SourceCodeset (struct codeset *)
        The pointer to an already existing codeset structure which
        will immediately be added to the created list. Please be
        carefull to add one codeset to multiple lists, especially
        when you do a CodesetsListDelete() to free the list.
        Default: NULL

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    Be careful when adding one codeset to more than one codeset list as
    you may run into problems when freeing the list afterwards.

   SEE ALSO
    codesets.library/CodesetsListCreateA
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsListRemoveA

   NAME
    CodesetsListRemoveA - removes a single or multiple codesets from a
                          previously created codeset list.

   SYNOPSIS
    result = CodesetsListRemoveA(attrs);
    D0                           A0

    BOOL CodesetsListRemoveA(struct TagItem *);

    result = CodesetsListRemove(tag1, ...);
    D0                          A0

    BOOL CodesetsListRemove(Tag, ...);

   FUNCTION
    This function allows to remove single or multiple codesets from a
    previously created codeset list. The removed codeset structures will
    also be freed/deleted per default.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        Pointer to a codeset structure which should be removed from
        its corresponding list. Per default its resources will also
        be internally freed.
        Default: NULL

      CSA_FreeCodesets (BOOL)
        If TRUE, all supplied codesets should also be freed/deleted,
        otherwise the codesets will just be removed from their lists.
        Default: TRUE

   RESULT
    result - TRUE on success otherwise FALSE

   NOTE
    The function will automatically prevent removal of codesets from the
    internal codeset list of codesets.library and will return FALSE in
    case a user tried to remove a codeset from the internal list.

   SEE ALSO
    codesets.library/CodesetsListDeleteA
    codesets.library/CodesetsListAddA


codesets.library/CodesetsUTF8CreateA

   NAME
    CodesetsUTF8CreateA - creates an UTF8 compliant string
                          interpretation out of a supplied source
                          string.


   SYNOPSIS
    utf8 = CodesetsUTF8CreateA(attrs);
                               A0
    UTF8 * CodesetsUTF8CreateA(struct TagItem *);

    utf8 = CodesetsUTF8Create(tag1, ...);
                              A0
    UTF8 * CodesetsUTF8Create(Tag, ...);


   FUNCTION
    Creates an UTF8 from a string which is encoded in specified
    codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source or less to convert just a part
        Default: string length of CSA_Source

      CSA_SourceCodeset (struct codeset *)
        The codeset in which the source string is encoded.
        Default: the system's default codeset

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole utf8. If CSA_Dest can't
        contain the utf8, a brand new buffer is allocated. If
        CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the utf8 string

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the UTF8 a new buffer is allocated
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, utf8, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(utf8, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

   RESULT
    utf8 - the utf8 string or NULL
           If CSA_DestHook is used always NULL.
           If CSA_DestHook is not used NULL means failure
           to allocate mem.

   EXAMPLE
    The shortest invocation is:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    In case you want to use your pool to allocate mem:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If your pool is to be arbitrated via a semaphore:
    -- cut here --
    UTF8   *utf8;
    STRPTR str;
    APTR   pool;
    struct SignalSemaphore *sem;

    if((utf8 = CodesetsUTF8Create(CSA_Source,     str,
                                  CSA_Pool,       pool,
                                  CSA_PoolSem,    sem,
                                  TAG_DONE)))
    {
        ...

        CodesetsFreeVecPooledA(pool,utf8,NULL);
    }
    -- cut here --


    If you want to use your own buffer to reduce mem
    allocation:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[256];

    if((utf8 = CodesetsUTF8Create(CSA_Source,  str,
                                  CSA_Dest,    buf,
                                  CSA_DestLen, sizeof(buf),
                                  TAG_DONE)))
    {
        ...

        if(utf8 != buf)
          CodesetsFreeA(utf8,NULL);
    }
    -- cut here --


    If your string are max MAXLEN chars long (e.g. image to be
    in a MUI application and you know the max size of your
    string gadgets), you should better supply your own buffer:
    -- cut here --
    UTF8   *utf8;
    STRPTR buf[MAXSIZE*6+1];

    if((utf8 = CodesetsUTF8Create(CSA_Source, str,
                                  CSA_Dest,   buf,
                                  CSA_Dest,   sizeof(buf),
                                  TAG_DONE)))
    {
        ...
    }
    -- cut here --


    If you strings are very large and so you are sure there is
    no mem for them and or you have your own reasons to do
    that:
    -- cut here --
    static ULONG ASM SAVEDS
    destFun(REG(a0, struct Hook *hook),
            REG(a2, struct convertMsg *msg),
            REG(a1, STRPTR buf))
    {
      printf(&quot;[%3ld] [%s]\n&quot;,msg-&gt;len,buf);
      if(msg-&gt;state == CSV_End)
        printf(&quot;\n&quot;);

      return 0;
    }

    struct Hook dest;
    dest.h_Entry = (HOOKFUNC)destFun;

    CodesetsUTF8Create(CSA_Source,    str,
                       CSA_DestHook,  &amp;dest,
                       TAG_DONE);
    -- cut here --

   SEE ALSO
    codesets.library/CodesetsUTF8ToStrA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8ToStrA

   NAME
    CodesetsUTF8ToStrA - converts an UTF8 encoded string into
                         a specified destination codeset.


   SYNOPSIS
    str = CodesetsUTF8ToStrA(attrs);
    D0                       A0

    STRPTR CodesetsUTF8ToStrA(attrs);

    str = CodesetsUTF8ToStr(tag1, ...);
    D0                      A0

    STRPTR CodesetsUTF8ToStr(Tag,...);


   FUNCTION
    Convert an utf8 string to a specified codeset.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_Source (STRPTR)
        The string which you want to convert. Must be supplied,
        otherwise the functions returns NULL.

      CSA_SourceLen (ULONG)
        Length of CSA_Source. Must be &gt; 0 or the function returns
        NULL.
        Default: string length of CSA_Source - strlen()

      CSA_Dest (STRPTR)
        Destination buffer. If you supply a valid buffer here, you
        must also set CSA_DestLen to the length of your buffer. If
        CSA_AllocIfNeeded is TRUE, CSA_DestLen is checked to see if
        CSA_Dest may contain the whole converted string. If CSA_Dest
        can't contain the output string, a brand new buffer is allocated.
        If CSA_AllocIfNeeded is FALSE, up to CSA_DestLen (ending '\0'
        included) are written to CSA_Dest. If CSA_DestHook is supplied,
        CSA_Dest is ignored.
        Default: NULL.

      CSA_DestCodeset (struct codeset *)
        The codeset to which the UTF8 string should be encoded to.
        Default: the system's default codeset

      CSA_DestHook (struct Hook *)
        Destination hook. If this is supplied, it is called with a
        partial converted string.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct convertMsg *msg),
                             REG(a1, STRPTR buf))

        struct Hook *hook
          Your hook

        STRPTR buf
          The partial '\0' terminated buffer

        msg-&gt;state - one of

          o CSV_Translating
            More calls to came

          o CSV_End
            Last call

        msg-&gt;Len
          length of string 'buf'

        You may define the min length of the buffer via CSA_DestLen.
        If so, accepted values are 16&lt;=v&lt;=sizeof_codeset_buffer.

        Don't count on this size to be fixed, even if you used
        CSA_DestLen !

      CSA_DestLen (ULONG)
        If CSA_DestHook is used, it represents the min length of the
        buffer that causes hook calls. Otherwise it is the size of
        the buffer supplied in CSA_Dest. So if CSA_DestHook is
        supplied, CSA_DestLen is optional, otherwise it is required.

      CSA_DestLenPtr (ULONG *)
        If supplied, will contain the length of the converted string.

      CSA_AllocIfNeeded (BOOL)
        If the destination buffer length is too small to contain
        the output string, a new buffer is allocated.
        Default: TRUE

      CSA_Pool (APTR)
        If a new destination buffer needs to be allocated (it happens
        if and only if CSA_DestHook is not used, CSA_AllocIfNeeded
        is TRUE, or if CSA_Dest buffer is too small for the utf8) this
        pool is used. The result must be freed via
        CodesetsFreeVecPooledA(pool, string, NULL).
        If CSA_Pool is not supplied, the destination buffer is allocated
        from the internal memory pool and must be freed via
        CodesetsFreeA(string, NULL).

      CSA_PoolSem (struct SignalSemaphore *)
        A semaphore to lock when using CSA_Pool

      CSA_ErrPtr (int *)
        Pointer to an integer variable which will be filled with the
        number of found issues (number of not convertable chars)
        Default: NULL

      CSA_MapForeignChars (BOOL)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. If this attribute is set, an internal
        replacement table will be used which tries to replace these
        &quot;foreign&quot; characters by &quot;looklike&quot; ASCII character sequences.
        Please note, that this functionality is mostly just usable by
        Latin users due to the straight mapping to ASCII (7bit).
        Default: FALSE

      CSA_MapForeignCharsHook (struct Hook *)
        If a character of the source string cannot be directly mapped
        to the destination codeset a &quot;?&quot; character will normally be used
        to signal this case. By using this attribute, a hook can be
        supplied which is called for every such foreign character.
        Within this hook the UTF8 sequence is supplied which cannot be
        directly mapped to the destination codeset. During the execution
        of the hook a replacement string might be specified, which in turn
        will be used by the internals of codesets.library to map this
        &quot;foreign&quot; char to a difference character or UTF8 sequence.

        If both, CSA_MapForeignChars and CSA_MapForeignCharsHook, are
        specified the hook will only be executed in case the internal
        routines don't supply an own mapping for the foreign UTF8 sequence.

        The hook function should be declared as:

        ULONG ASM SAVEDS fun(REG(a0, struct Hook *hook),
                             REG(a2, struct replaceMsg *msg),
                             REG(a1, void *dummy))

        struct Hook *hook
          Your hook

        msg-&gt;dst
          place your desired replacement string here

        msg-&gt;src
          the UTF8 sequence to be replaced, this string is READ-ONLY!

        msg-&gt;srclen
          the length of the UTF8 sequence to be replaced, do NOT peek
          beyond this limit.

        The return value of this hook function is the length of the replacement
        string. Return zero if no replacement did happen. Positive values will
        be treated as lengths of ASCII strings. Negative values signals a
        replacement by another UTF8 sequence. Please note, that in case you
        supply a UTF8 sequence as a replacement for the &quot;foreign&quot; UTF8, your
        hook might be called again if this sequence can still not be mapped to
        the destination codesets, thus is again a &quot;foreign&quot; sequence.


   RESULT
    str - the string or NULL
          If CSA_DestHook is used always NULL.
          If CSA_DestHook is not used NULL means failure
          to allocate mem.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8Len


codesets.library/CodesetsUTF8Len

   NAME
    CodesetsUTF8Len - returns the length of a supplied utf8 string.

   SYNOPSIS
    len = CodesetsUTF8Len(utf8);
    D0                    A0

    ULONG CodesetsUTF8Len(UTF8 *);

   FUNCTION
    Returns the amount of real characters stored in a supplied UTF8
    string. This is _NOT_ the space required to store the UTF8 string,
    it is the actual number of _real_ character the UTF8 represents.

   INPUTS
    utf8 - pointer to the UTF8 string generated by the internal
           functions of codesets.library

   RESULT
    len - length of utf8

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsValidUTF8

   NAME
    CodesetsIsValidUTF8 - tells if a supplied standard string is meant to
                          carry a perfectly valid UTF8 sequence

   SYNOPSIS
    result = CodesetsIsValidUTF8(str);
    D0                           A0

    BOOL CodesetsIsValidUTF8(STRPTR);

   FUNCTION
    Returns TRUE in case the supplied string only contains char sequences
    which are compatible to the UTF8 standard.

   INPUTS
    str - a standard STRPTR string.

   RESULT
    result - TRUE in case the string conatins valid UTF8 data.

   NOTE
    This function uses the common 'GOOD_UCS' macro together with parsing
    the whole string. This means that it will only return TRUE in case
    the supplied string only contains UTF8 sequences. A mixture of UTF8
    and non-UTF8 sequences will result in the function returning FALSE.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8

   NAME
    CodesetsIsLegalUTF8 - check a UTF8 sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8(source, length);
                              A0      D0

    ULONG CodesetsIsLegalUTF8(UTF8 *, ULONG);


   FUNCTION
    Checks if source is a valid UTF8 sequence generated
    by the internal functions of codesets.library

   INPUTS
    source - the char sequence to check
    length - size of source

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsIsLegalUTF8Sequence

   NAME
    CodesetsIsLegalUTF8Sequence - check a char sequence

   SYNOPSIS
    res = CodesetsIsLegalUTF8Sequence(source, end);
                                      A0      A1

    ULONG CodesetsIsLegalUTF8(UTF8 *, UTF8 *);

   FUNCTION
    Check if source is a valid UTF8 sequence within the
    source and end boundaries.

   INPUTS
    source - the char sequence to check
    end - pointer to the end of the sequence to check

   RESULT
    res - TRUE or FALSE

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA
    codesets.library/CodesetsUTF8ToStrA


codesets.library/CodesetsStrLenA

   NAME
    CodesetsStrLenA - returns the length of the source string
                      in case it will be converted to an UTF8
                      string.

   SYNOPSIS
    len = CodesetsStrLenA(str, attrs)
                          A0   A1

    ULONG CodesetsStrLenA(STRPTR, struct TagItem *);

    len = CodesetsStrLen(str, tag1, ...);
                         A0   A1

    ULONG CodesetsStrLen(STRPTR, Tag, ...);

   FUNCTION
    Return the length (size) of str in case it will be converted to
    an UTF8 compliant string.

   INPUTS
    str - the string to obtain length of
    attrs - a list of additional tag items. Valid items are:

      CSA_SourceCodeset (struct codeset *)
        The codeset the source string is encoded in.
        Default: the system's default codeset

      CSA_SourceLen (ULONG)
        The length of str
        Default: string length of CSA_Source

   RESULT
    len - the length of the string if it will be converted to
          an UTF8 string.

   SEE ALSO
    codesets.library/CodesetsUTF8CreateA


codesets.library/CodesetsConvertUTF16toUTF32

   NAME
    CodesetsConvertUTF16toUTF32 - converts from UTF16 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF32(const UTF16 **,const UTF16 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF16toUTF8

   NAME
    CodesetsConvertUTF16toUTF8 - converts from UTF16 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF16toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF16toUTF8(const UTF16 **,const UTF16 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF16 to UTF8.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF16

   NAME
    CodesetsConvertUTF32toUTF16 - converts from UTF32 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF16(const UTF32 **,const UTF32 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF32toUTF8

   NAME
    CodesetsConvertUTF32toUTF8 - converts from UTF32 to UTF8

   SYNOPSIS
    res = CodesetsConvertUTF32toUTF8(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF32toUTF8(const UTF32 **,const UTF32 *,UTF8 **,UTF8 *,ULONG);

   FUNCTION
    Converts UTF32 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF16

   NAME
    CodesetsConvertUTF8toUTF16 - converts from UTF8 to UTF16

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF16(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF16(const UTF8 **,const UTF8 *,UTF16 **,UTF16 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF16.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsConvertUTF8toUTF32

   NAME
    CodesetsConvertUTF8toUTF32 - converts from UTF8 to UTF32

   SYNOPSIS
    res = CodesetsConvertUTF8toUTF32(sourceStart,sourceEnd,targetStart,targetEnd,flags );
    D0                                A0          A1        A2          A3        D0

    ULONG CodesetsConvertUTF8toUTF32(const UTF8 **,const UTF8 *,UTF32 **,UTF32 *,ULONG);

   FUNCTION
    Converts UTF8 to UTF32.

   INPUTS

   RESULT

   SEE ALSO


codesets.library/CodesetsDecodeB64A

   NAME
    CodesetsDecodeB64A - decodes a supplied base64 encoded string
                         or file into plain text charwise.

   SYNOPSIS
    res = CodesetsDecodeB64A(attrs);
    D0                       A0

    ULONG CodesetsDecodeB64A(struct TagItem *);

    res = CodesetsDecodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsDecodeB64A(Tag, ....);

   FUNCTION
    Decodes a string or a complete base64 encoded file to a
    plain text buffer or also a destination file

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to decode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64FLG_NtCheckErr (BOOL)
        Don't stop on error.

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be still be encoded to.

   SEE ALSO
    codesets.library/CodesetsEncodeB64A


codesets.library/CodesetsEncodeB64A

   NAME
    CodesetsEncodeB64A - encodes a string or whole file
                         to base64

   SYNOPSIS
    res = CodesetsEncodeB64A(attrs);
    D0                       A0

    ULONG CodesetsEncodeB64A(struct TagItem *);

    res = CodesetsEncodeB64(tag1, ...);
    D0                      A0

    ULONG CodesetsEncodeB64(Tag, ....);

   FUNCTION
    Encodes the supplied string or file to either a whole
    buffer or also to a file.

   INPUTS
    attrs - a list of mandatory tag items. Valid items are:

      CSA_B64SourceString (STRPTR)
        The source string to encode

      CSA_B64SourceLen (ULONG)
        The length of CSA_B64SourceString. Must be supplied if
        CSA_B64SourceString is used.

      CSA_B64SourceFile (STRPTR)
        Source file name.

      CSA_B64DestPtr (STRPTR *)
        Destination buffer pointer. Set to the allocated buffer.
        Must be supplied if CSA_B64DestFile is not used. To
        free the buffer use CodesetsFreeA().

      CSA_B64DestFile (STRPTR)
        Destination file name. Must be supplied if
        CSA_B64DestPtr is used.

      CSA_B64MaxLineLen (ULONG)
        Maximum length of encoded lines. 0&lt;v&lt;256
        Default: 72

      CSA_B64Unix (ULONG)
        If TRUE eol is \n (LF), otherwise \r\n (CRLF).
        Default: TRUE

   RESULT
    res - result, one of (if 0 OK, if &gt;0 error)
        CSR_B64_ERROR_OK
        CSR_B64_ERROR_MEM
        CSR_B64_ERROR_DOS
        CSR_B64_ERROR_INCOMPLETE
        CSR_B64_ERROR_ILLEGAL

   NOTE
    It fully operates charwise and doesn't take respect of the
    individual codeset the decoded data may be encoded to.

   SEE ALSO
    codesets.library/CodesetsDecodeB64A

&lt;/pre&gt;</text>
      <sha1>430tv26chfy7wbpgddoq1e6c0eualh0</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:Heathcliff00</title>
    <ns>3</ns>
    <id>475968</id>
    <revision>
      <id>4669768</id>
      <parentid>4623066</parentid>
      <timestamp>2026-09-12T16:33:00Z</timestamp>
      <contributor>
        <username>QueerEcofeminist</username>
        <id>474408</id>
      </contributor>
      <minor />
      <comment>QueerEcofeminist moved page [[User talk:Harshvardhanrai0905]] to [[User talk:Heathcliff00]]: Automatically moved page while renaming the user &quot;[[Special:CentralAuth/Harshvardhanrai0905|Harshvardhanrai0905]]&quot; to &quot;[[Special:CentralAuth/Heathcliff00|Heathcliff00]]&quot;</comment>
      <origin>4623066</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="887" sha1="388rh0vvkp9ts1ntetfk0v91lo0nj4l" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:User:Harshvardhanrai0905/sandbox]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time. The reason I provided was: &lt;blockquote&gt;&lt;strong&gt;Out of scope&lt;/strong&gt;&lt;/blockquote&gt; If you believe that your page should not be deleted, please post a message on [[User talk:Harshvardhanrai0905/sandbox|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:JJPMaster|let me know]]. Thank you! [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:27, 21 June 2025 (UTC)</text>
      <sha1>388rh0vvkp9ts1ntetfk0v91lo0nj4l</sha1>
    </revision>
  </page>
  <page>
    <title>User:Dom walden/Multivariate Analytic Combinatorics/Homology of Critical Points</title>
    <ns>2</ns>
    <id>480750</id>
    <revision>
      <id>4669761</id>
      <parentid>4669454</parentid>
      <timestamp>2026-09-12T13:52:51Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669761</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="36976" sha1="jal0zh3fgmk662jg1errjpqh5roqpxj" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>jal0zh3fgmk662jg1errjpqh5roqpxj</sha1>
    </revision>
    <revision>
      <id>4669848</id>
      <parentid>4669761</parentid>
      <timestamp>2026-09-13T07:44:14Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669848</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="38476" sha1="dac631zlyq4crhg0ynlwoek81pk24yx" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>dac631zlyq4crhg0ynlwoek81pk24yx</sha1>
    </revision>
    <revision>
      <id>4669850</id>
      <parentid>4669848</parentid>
      <timestamp>2026-09-13T07:47:38Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669850</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="39033" sha1="gm8gbj707crpaqhiw0xp6b11eokkja5" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>gm8gbj707crpaqhiw0xp6b11eokkja5</sha1>
    </revision>
    <revision>
      <id>4669856</id>
      <parentid>4669850</parentid>
      <timestamp>2026-09-13T08:16:24Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669856</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="39354" sha1="s9wf8ol3xqft163v71xp8un1codwvxe" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

...&lt;ref&gt;Mather 2012, pp. 496-497.&lt;/ref&gt;

We prove there is a homeomorphism &lt;math display=&quot;inline&quot;&gt;f: Z \to h^{-1}(0) \times \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;, where &lt;math display=&quot;inline&quot;&gt;\pi: h^{-1}(0) \times \R&lt;/math&gt; is projection to the second factor.&lt;ref&gt;Mather 2012, pp. 497.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>s9wf8ol3xqft163v71xp8un1codwvxe</sha1>
    </revision>
    <revision>
      <id>4669858</id>
      <parentid>4669856</parentid>
      <timestamp>2026-09-13T08:42:45Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */ Finish(?) proof of corollary 10.2</comment>
      <origin>4669858</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="40544" sha1="roughyqz4ack2mgo4fwll6zdienikdz" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

...&lt;ref&gt;Mather 2012, pp. 496-497.&lt;/ref&gt;

We prove there is a homeomorphism &lt;math display=&quot;inline&quot;&gt;f: Z \to h^{-1}(0) \times \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;, where &lt;math display=&quot;inline&quot;&gt;\pi: h^{-1}(0) \times \R \to \R&lt;/math&gt; is projection to the second factor.

For the coordinate vector field &lt;math display=&quot;inline&quot;&gt;\partial&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, by [prop 9.1] there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;f_* \tilde\partial(v) = \partial(h(v))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;. By [prop 10.1], &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; generates a local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;h(\alpha(t,v)) = h(v) + t&lt;/math&gt;

&lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is proper and [d] holds, so &lt;math display=&quot;inline&quot;&gt;J = \R \times Z&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;f(v) = (\alpha(-t, v), h(v))&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; maps &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; into &lt;math display=&quot;inline&quot;&gt;h^{-1}(0) \times \R&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;\bar f: h^{-1}(0) \times \R \to Z&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;\bar f(v, t) = \alpha(t, v)&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f \bar f = \bar f f = Id&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; is a homeomorphism.&lt;ref&gt;Mather 2012, pp. 497.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>roughyqz4ack2mgo4fwll6zdienikdz</sha1>
    </revision>
    <revision>
      <id>4669867</id>
      <parentid>4669858</parentid>
      <timestamp>2026-09-13T09:28:16Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669867</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="40611" sha1="i95g7qrittby68w6w3aslagnoq3szdw" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification, &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

For the latter-most condition, if it did not hold then there exists...&lt;ref&gt;Mather 2012, pp. 496-497.&lt;/ref&gt;

We prove there is a homeomorphism &lt;math display=&quot;inline&quot;&gt;f: Z \to h^{-1}(0) \times \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;, where &lt;math display=&quot;inline&quot;&gt;\pi: h^{-1}(0) \times \R \to \R&lt;/math&gt; is projection to the second factor.

For the coordinate vector field &lt;math display=&quot;inline&quot;&gt;\partial&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, by [prop 9.1] there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;f_* \tilde\partial(v) = \partial(h(v))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;. By [prop 10.1], &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; generates a local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;h(\alpha(t,v)) = h(v) + t&lt;/math&gt;

&lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is proper and [d] holds, so &lt;math display=&quot;inline&quot;&gt;J = \R \times Z&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;f(v) = (\alpha(-t, v), h(v))&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; maps &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; into &lt;math display=&quot;inline&quot;&gt;h^{-1}(0) \times \R&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;\bar f: h^{-1}(0) \times \R \to Z&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;\bar f(v, t) = \alpha(t, v)&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f \bar f = \bar f f = Id&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; is a homeomorphism.&lt;ref&gt;Mather 2012, pp. 497.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>i95g7qrittby68w6w3aslagnoq3szdw</sha1>
    </revision>
    <revision>
      <id>4669868</id>
      <parentid>4669867</parentid>
      <timestamp>2026-09-13T09:29:18Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669868</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="40614" sha1="k6jq6n9spgclj9u1epitaaqv5ggaj0g" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification and &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; and controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a smooth vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

For the latter-most condition, if it did not hold then there exists...&lt;ref&gt;Mather 2012, pp. 496-497.&lt;/ref&gt;

We prove there is a homeomorphism &lt;math display=&quot;inline&quot;&gt;f: Z \to h^{-1}(0) \times \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;, where &lt;math display=&quot;inline&quot;&gt;\pi: h^{-1}(0) \times \R \to \R&lt;/math&gt; is projection to the second factor.

For the coordinate vector field &lt;math display=&quot;inline&quot;&gt;\partial&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, by [prop 9.1] there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;f_* \tilde\partial(v) = \partial(h(v))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;. By [prop 10.1], &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; generates a local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;h(\alpha(t,v)) = h(v) + t&lt;/math&gt;

&lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is proper and [d] holds, so &lt;math display=&quot;inline&quot;&gt;J = \R \times Z&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;f(v) = (\alpha(-t, v), h(v))&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; maps &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; into &lt;math display=&quot;inline&quot;&gt;h^{-1}(0) \times \R&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;\bar f: h^{-1}(0) \times \R \to Z&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;\bar f(v, t) = \alpha(t, v)&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f \bar f = \bar f f = Id&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; is a homeomorphism.&lt;ref&gt;Mather 2012, pp. 497.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>k6jq6n9spgclj9u1epitaaqv5ggaj0g</sha1>
    </revision>
    <revision>
      <id>4669871</id>
      <parentid>4669868</parentid>
      <timestamp>2026-09-13T09:46:09Z</timestamp>
      <contributor>
        <username>Dom walden</username>
        <id>3209423</id>
      </contributor>
      <comment>/* Thom's isotopy lemma */</comment>
      <origin>4669871</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="40616" sha1="era8v6ovtjsnaiyvpjxolbfx5r0dbph" xml:space="preserve">== Introduction ==

Morse theory tells us that the topology of M only changes at its critical points.

The &quot;Morse data&quot; tells us the topology at each critical point.

Attaching this Morse data together gives us a space which is homopotically eqivalent to M.

This space is a &quot;cell complex&quot;, which has an easy to calculate homology.

Theorem: Our domain of convergence is homotopic to a cell complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;This is theorem D.23 in Pemantle, Wilson and Melczer 2024, pp. 546. Also theorem in section 1.2*/5.2* in SMT pp. 200.&lt;/ref&gt;

Proof:
# &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is our entire domain, &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; our variety
# Project our entire domain to complex projective space &lt;math display=&quot;inline&quot;&gt;Z = \pi(X) \subset \C\mathbb{P}^n - H&lt;/math&gt; [define H]
# Define a linear subspace &lt;math display=&quot;inline&quot;&gt;G \subset \C\mathbb{P}^n&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d - 1&lt;/math&gt;
# Define a Morse function on &lt;math display=&quot;inline&quot;&gt;f: \C\mathbb{P}^n \to \R&lt;/math&gt; which approximates the distance from &lt;math display=&quot;inline&quot;&gt;G&lt;/math&gt; and such that &lt;math display=&quot;inline&quot;&gt;f^{-1}(0) = G&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f^{-1}(1) = H&lt;/math&gt;
# We &quot;build&quot; &lt;math display=&quot;inline&quot;&gt;X - \mathcal{V}&lt;/math&gt; from &lt;math display=&quot;inline&quot;&gt;\pi^{-1}(G \cap Z) \cap (X - \mathcal{V})&lt;/math&gt; by attaching CW complexes at critical points which are of at most dimension &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# At a critical point, the normal Morse data is &lt;math display=&quot;inline&quot;&gt;(J, K) = \coprod_x (J_x, K_x)&lt;/math&gt; and the relative complex link is &lt;math display=&quot;inline&quot;&gt;\mathcal{L}^\pi = \coprod_x \mathcal{L}_x&lt;/math&gt;
# We show that the quotient &lt;math display=&quot;inline&quot;&gt;J_x/K_x&lt;/math&gt; is homotopic to a CW complex of dimension &lt;math display=&quot;inline&quot;&gt;\leq 2n - d - 1&lt;/math&gt;
# The neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;J_x&lt;/math&gt; is homeomorphic to the cone in &lt;math display=&quot;inline&quot;&gt;L_x(X - \mathcal{V})&lt;/math&gt;, and removing the point &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; increases the homotopy dimension to at most the homotopy dimension of &lt;math display=&quot;inline&quot;&gt;L_x&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;(J_x \cup \{x\}, K_x)&lt;/math&gt; is homotopic to &lt;math display=&quot;inline&quot;&gt;(\text{cone}(\mathcal{L}_x), \mathcal{L}_x)&lt;/math&gt;
# &lt;math display=&quot;inline&quot;&gt;\mathcal{L}_x&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;
# The tangential Morse data at the critical point is homotopic to the pair &lt;math display=&quot;inline&quot;&gt;(D^\lambda, \partial D^\lambda)&lt;/math&gt;
# Therefore, at each critical point a space has been added homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.

Theorem: If &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is the complement in &lt;math display=&quot;inline&quot;&gt;\C^n&lt;/math&gt; of a complex variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; is homotopic to a CW complex of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 546.&lt;/ref&gt;

Proof:
# We build &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; by attaching cells of dimension at most &lt;math display=&quot;inline&quot;&gt;2n - d - 1&lt;/math&gt; at each critical point.
## Prove that we can do this without changing the homotopy(?)
## We use Thom's Isotopy Lemma to prove that there is a strong deformation retraction, stopping only at critical points.
# Prove these cells are a product of the normal and tangential Morse data.
## Normal data: &lt;math display=&quot;inline&quot;&gt;(\mathcal{L}(S), \partial \mathcal{L}(S)) \times (D^1, \partial D^1)&lt;/math&gt; [GM pp. 18]
## Tangential data: &lt;math display=&quot;inline&quot;&gt;(B_\delta \cap f^{-1}[v - \epsilon, v + \epsilon], B_\delta \cap f^{-1}(v - \epsilon))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; restricted to &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (or &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;?) [GM pp. 63-64]
# If &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; is the dimension of the strata, then
## If &lt;math display=&quot;inline&quot;&gt;k = d&lt;/math&gt; then it is a smooth point and the cell is the product of &lt;math display=&quot;inline&quot;&gt;S^{2(n-d)-1}&lt;/math&gt; and the tangential data is dimension at most &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;.
## If &lt;math display=&quot;inline&quot;&gt;k &lt; d&lt;/math&gt;, ...

&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 547.&lt;/ref&gt;

== Example in one dimension ==

Domain with singularities v_1, v_2, ..., v_i

Define our height function f...

Start with our entire domain X

Reduce from X to X_i+ by using Thom's Isotopy lemma to do a strong deformation retract

== Thom's isotopy lemma ==

We present a modified version of Thom's isotopy lemma, less general than the original but more obviously relevant to our situation.

Theorem: Suppose &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is a closed subset of a smooth manifold &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; which admits a Whitney stratification and &lt;math display=&quot;inline&quot;&gt;h : M \to \R&lt;/math&gt; is a proper Morse function which has no critical values on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. Then, the level sets of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; are homeomorphic by a homeomorphism that preserves the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;For various versions of the full statement of the theorem, see Mather 2012, pp. 499, Goresky and MacPherson 1988, pp. 41, or Pemantle, Wilson and Melczer 2024, pp. 541.&lt;/ref&gt;

Proof:
# Construct control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.
## [Prop 7.1] If &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an abstract stratified set and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; a controlled submersion.
# A controlled submersion has, for any smooth vector field on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, a controlled vector field on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; (a &quot;lift&quot;?)&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;
# A controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;
# This makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a locally trivial fibration. [Prop 10.2]&lt;ref&gt;Mather 2012, pp. 499.&lt;/ref&gt;

Control data:

A system of '''control data''' for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; consists of, for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;,
* a '''tubular neighbourhood''' &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt;
* a '''tubular projection function''' &lt;math display=&quot;inline&quot;&gt;\pi_X: T_X \to X&lt;/math&gt;, and
* a '''tubular distance function''' &lt;math display=&quot;inline&quot;&gt;\rho_X: T_X \to \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\rho_X^{-1}(0) = X&lt;/math&gt;&lt;ref&gt;Goresky and MacPherson 1988, pp. 42.&lt;/ref&gt;

[illustration]

such that if &lt;math display=&quot;inline&quot;&gt;X &lt; Y&lt;/math&gt; are strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, then

&lt;math display=&quot;block&quot;&gt;\pi_X \pi_Y(m) = \pi_X(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\rho_X \pi_Y(m) = \rho_X(m)&lt;/math&gt;

for all &lt;math display=&quot;inline&quot;&gt;m \in |T_X| \cap |T_Y|&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi_Y(m) \in |T_X|&lt;/math&gt;.

If, for all strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; and all &lt;math display=&quot;inline&quot;&gt;m \in |T_X|&lt;/math&gt;, we have &lt;math display=&quot;inline&quot;&gt;h \pi_X(m) = h(m)&lt;/math&gt;, then this control data will be said to be compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is smooth on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; and is a submersion for each strata then there exists a family of control data for &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 488, prop 7.1.&lt;/ref&gt;

Let &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. We prove by induction on &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;.

To construct the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt; of a stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension less than &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;l \leq k&lt;/math&gt;, let &lt;math display=&quot;inline&quot;&gt;U_l&lt;/math&gt; denote the union of all &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l&lt;/math&gt;. Let &lt;math display=&quot;inline&quot;&gt;X_l = U_l \cap X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;l = k&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X_k = \empty&lt;/math&gt;. Assume by induction that &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; has been constructed and that if &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\dim Y \geq l + 1&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{l+1} = \pi_{T_{l+1}}&lt;/math&gt;) then&lt;ref&gt;Mather 2012, pp. 489-490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y(m).&lt;/math&gt;

We wish to construct a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X&lt;/math&gt; whose restriction to &lt;math display=&quot;inline&quot;&gt;|T_Y| \cap X_{l+1}&lt;/math&gt; is isomorphic to the restriction of &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; such that if &lt;math display=&quot;inline&quot;&gt;m \in |T_{X,Y}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}(m) \in |T_Y|&lt;/math&gt; (&lt;math display=&quot;inline&quot;&gt;\pi_{X,Y} = \pi_{T_{X,Y}}&lt;/math&gt;) then

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{X,Y}(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{X,Y}(m) = \pi_Y(m).&lt;/math&gt;

By shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt; if necessary, this relation is already satisfied if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}| \cap |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y|&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;T_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}&lt;/math&gt; in place of &lt;math display=&quot;inline&quot;&gt;\pi_{X,Y}&lt;/math&gt;. By the definition, if &lt;math display=&quot;inline&quot;&gt;m \in |T_{l+1}|&lt;/math&gt; then there exists &lt;math display=&quot;inline&quot;&gt;Z &lt; X&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;\dim Z &gt; l&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Z|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Z|&lt;/math&gt;. We have that &lt;math display=&quot;inline&quot;&gt;\pi_{l+1}(m) \in |T_Y| \cap |T_Z|&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;Y &lt; Z&lt;/math&gt;. Therefore&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_{l+1}(m) = \rho_Y \pi_Z \pi_{l+1}(m) = \rho_Y \pi_Z(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_{l+1}(m) = \pi_Y \pi_Z \pi_{l+1}(m) = \pi_Y \pi_Z(m) = \pi_Y(m).&lt;/math&gt;

We can prove that, by shrinking &lt;math display=&quot;inline&quot;&gt;|T_Y|&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X \to \R \times Y&lt;/math&gt; is a submersion [prop 7.3?] and that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y) \pi_{X,Y}(m) = (\rho_Y, \pi_Y)(m)&lt;/math&gt;(?).

To prove it is a submersion, for the tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T = (E, \epsilon, \psi)&lt;/math&gt; there exists a smooth positive function &lt;math display=&quot;inline&quot;&gt;\epsilon'&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): Y \cap |T|_{\epsilon'}^0 \to \R \times X,&lt;/math&gt;

where &lt;math display=&quot;inline&quot;&gt;|T|_{\epsilon'}^0 = \psi(B_\epsilon \cap B_{\epsilon'})&lt;/math&gt;, is a submersion. If &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt; is the set &lt;math display=&quot;inline&quot;&gt;y \in |T|&lt;/math&gt; such that the rank of

&lt;math display=&quot;block&quot;&gt;(\rho_T, \pi_T): T \cap |T| \to \R \times X&lt;/math&gt;

at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is less than &lt;math display=&quot;inline&quot;&gt;\dim(\R \times X)&lt;/math&gt;. We need to prove that for any &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; there exists a neighbourhood of &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; which does not intersect with &lt;math display=&quot;inline&quot;&gt;\Sigma&lt;/math&gt;, i.e. the map is not a submersion in this neighbourhood. It follows from [lemma 7.2] that it is enough to prove for &lt;math display=&quot;inline&quot;&gt;M = \R^m&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;X = \R^{m-c} \times 0_c&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; is the '''standard tubular neighbourhood'''.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

By standard tubular neighbourhood, we mean the trivial bundle with base &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt; and fibre &lt;math display=&quot;inline&quot;&gt;\R^c&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\pi: \R^m \to \R^{m-c}&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 488.&lt;/ref&gt;

For &lt;math display=&quot;inline&quot;&gt;y \in |T| - \R^{m-c}&lt;/math&gt;, the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; is the orthogonal complement of &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; in &lt;math display=&quot;inline&quot;&gt;\R^m&lt;/math&gt;. By the Whitney conditions, we have that for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;(\R^{m-c} \times 0_c) \oplus \stackrel{\frown}{y \pi_T(y)}&lt;/math&gt; is close to the set of &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; planes in &lt;math display=&quot;inline&quot;&gt;m-&lt;/math&gt;space to an &lt;math display=&quot;inline&quot;&gt;m - c + 1&lt;/math&gt; plane in &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt;. Therefore, for &lt;math display=&quot;inline&quot;&gt;y&lt;/math&gt; near enough to &lt;math display=&quot;inline&quot;&gt;\R^{m-c}&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;TY_y&lt;/math&gt; is transverse to the kernal of the differential of &lt;math display=&quot;inline&quot;&gt;(\pi_T, \rho_T)&lt;/math&gt; and, therefore, is a submersion when restricted to &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 489.&lt;/ref&gt;

To prove that &lt;math display=&quot;inline&quot;&gt;T_{X,Y}&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;(\rho_Y, \pi_Y): |T_Y| \cap X_{l+1} \to \R \times Y&lt;/math&gt;...&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

Therefore, there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X_0&lt;/math&gt; satisfying

&lt;math display=&quot;block&quot;&gt;\rho_Y \pi_0(m) = \rho_Y(m),&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\pi_Y \pi_0(m) = \pi_Y(m).&lt;/math&gt;

From this we can prove that &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; is compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. Replacing &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a smaller tubular neighbourhood if necessary we can assume &lt;math display=&quot;inline&quot;&gt;m \in |T_0|&lt;/math&gt; such that for some &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;m \in |T_Y|&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi_0(m) \in |T_Y|&lt;/math&gt;, then&lt;ref&gt;Mather 2012, pp. 490.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;h \pi_0(m) = h \pi_Y \pi_0(m) = h \pi_Y(m) = h(m).&lt;/math&gt;

By the generalised tubular neighourhood theorem [prop 7.2?], we can replace &lt;math display=&quot;inline&quot;&gt;T_0&lt;/math&gt; with a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; compatible with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;. This completes the construction of &lt;math display=&quot;inline&quot;&gt;T_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 491.&lt;/ref&gt;

This makes &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; an '''abstract stratified set''' with axioms...&lt;ref&gt;Mather 2012, pp. 491-492.&lt;/ref&gt;

This also makes &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; a '''controlled submersion''' because
# &lt;math display=&quot;inline&quot;&gt;h|X: X \to \R&lt;/math&gt; is a smooth submersion on each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, and
# for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; there is a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_X(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in T'_X&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

[picture]

We define a '''stratified vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a family of smooth vector fields &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt;, one for each strata &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

We define a '''controlled vector field''' &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; to be a stratified vector field such that for any strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; there exists a tubular neighbourhood &lt;math display=&quot;inline&quot;&gt;T'_Y&lt;/math&gt; such that for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and any &lt;math display=&quot;inline&quot;&gt;v \in T'_X \cap X&lt;/math&gt;&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

&lt;math display=&quot;block&quot;&gt;\eta_X \rho_{Y,X}(v) = 0,&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;(\pi_{Y,X})_* \eta_X(v) = \eta_Y (\pi_{Y,X}(v)).&lt;/math&gt;

We prove that if &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is a controlled submersion then, for any smooth vector field &lt;math display=&quot;inline&quot;&gt;\zeta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt; there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h_* \eta(v) = \zeta(h(v))&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 493.&lt;/ref&gt;

Proceeding by induction on the maximum dimension of the strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, we define &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; to be the union of strata of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;. The tubular neighbourhood of &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; is the intersection of the tubular neighbourhoods of each strata in &lt;math display=&quot;inline&quot;&gt;Z_k&lt;/math&gt; with &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;. The projection and distance functions are the restrictions of the respective functions of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;.

It is trivially true when the maximum dimension of strata in &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is zero. Assume it is true for &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt; and construct each &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; separately for each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of dimension &lt;math display=&quot;inline&quot;&gt;k + 1&lt;/math&gt;.

By the assumption that we have controlled vector fields for all strata &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; of dimension at most &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;, we have the two control conditions defined above for any &lt;math display=&quot;inline&quot;&gt;X &gt; Y&lt;/math&gt; and that there is a neighbourhood &lt;math display=&quot;inline&quot;&gt;T^1_Y&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;h(v) = h \pi_Y(v)&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in T^1_Y&lt;/math&gt;.

We want to prove that for all &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt;, the control conditions are satisfied for all &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt; and that &lt;math display=&quot;inline&quot;&gt;h_*\eta_X(v) = \zeta(v)&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in X&lt;/math&gt;.

Take a point &lt;math display=&quot;inline&quot;&gt;x \in X&lt;/math&gt; and define the set &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; of strata &lt;math display=&quot;inline&quot;&gt;Y &lt; X&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;v \in T^2_Y&lt;/math&gt;. &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is totally ordered since if &lt;math display=&quot;inline&quot;&gt;Y_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;Y_2&lt;/math&gt; are not comparable then &lt;math display=&quot;inline&quot;&gt;T^2_{Y_1} \cap T^2_{Y_2} = \empty&lt;/math&gt;. Therefore, there is a largest member &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;.

Assume the control conditions hold for &lt;math display=&quot;inline&quot;&gt;Y = Y_v&lt;/math&gt;. Then they hold for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. For, either &lt;math display=&quot;inline&quot;&gt;Y_i = Y&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;Y_i &lt; Y&lt;/math&gt;. In the latter case, &lt;math display=&quot;inline&quot;&gt;\pi_Y(v) \in T^1_{Y_i}&lt;/math&gt; (by the choice of &lt;math display=&quot;inline&quot;&gt;T^2_Y&lt;/math&gt;'s [is this why?]. Then

&lt;math display=&quot;block&quot;&gt;\begin{align}
\eta_X(v) \rho_{Y_i,X}(v) &amp;= \eta_X \rho_{Y_i,Y} \pi_{Y,X}(v) \\
&amp;= (\pi_{Y,X})_* \eta_X(v) \rho_{Y_i,Y} \\
&amp;= \eta_Y(\pi_{Y,X}(v)) \rho_{Y_i,Y} \\
&amp;= 0
\end{align}&lt;/math&gt;

and

&lt;math display=&quot;block&quot;&gt;\begin{align}
(\pi_{Y_i,X})_* \eta_X(v) &amp;= (\pi_{Y_i,Y})_* (\pi_{Y,X})_* \eta_X(v) \\
&amp;= (\pi_{Y_i,Y})_* \eta_Y(v) (\pi_{Y,X}) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,Y} \pi_{Y,X}(v)) \\
&amp;= \eta_{Y_i}(\pi_{Y_i,X}(v))
\end{align}&lt;/math&gt;

and, therefore, condition holds for all &lt;math display=&quot;inline&quot;&gt;Y_i \in S_v&lt;/math&gt;. Also,

&lt;math display=&quot;block&quot;&gt;\begin{align}
h_* \eta_X(v) &amp;= (h \circ \pi_{Y,X})_* \eta_X(v) \\
&amp;= h_* \eta_Y (\pi_{Y,X}(v)) \\
&amp;= \zeta(f(v))
\end{align}&lt;/math&gt;

and, therefore, the conclusion of the theorem holds at &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt;.

This shows we can construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; satisfying the control conditions when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is non-empty and satisfying the theorem when &lt;math display=&quot;inline&quot;&gt;S_v&lt;/math&gt; is empty. The set of vectors satisfying these conditions is convex in &lt;math display=&quot;inline&quot;&gt;TX_v&lt;/math&gt;, and so we construct &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; globally via a partition of unity.&lt;ref&gt;Mather 2012, pp. 493-495.&lt;/ref&gt;

Finally, we prove that a controlled vector field has a unique one-parameter family of homeomorphisms of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; which commute with &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt;.&lt;ref&gt;Mather 2012, this combines Proposition 10.1 and Corollary 10.2 on pp. 496 and 497, respectively.&lt;/ref&gt;

For each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;\eta_X&lt;/math&gt; generates a unique smooth local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; of diffeomorphisms of &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; (by standard results of differential geometry), such that &lt;math display=&quot;inline&quot;&gt;\frac{d}{dt} \alpha(t, v)|_{t=0} = \eta_X(v)&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;J_X&lt;/math&gt; is an open subset of &lt;math display=&quot;inline&quot;&gt;\R \times Z&lt;/math&gt;, ...

If we define &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; by

&lt;math display=&quot;block&quot;&gt;J = \bigcup_{X \in S} J_X&lt;/math&gt;
&lt;math display=&quot;block&quot;&gt;\alpha = \bigcup_{X \in S} \alpha_X&lt;/math&gt;

we can prove that this is a local one-parameter family of homeomorphisms.&lt;ref&gt;Mather 2012, pp. 496.&lt;/ref&gt;

Firstly, it is clear that
# &lt;math display=&quot;inline&quot;&gt;0 \times Z \subseteq J&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\alpha(0, v) = v&lt;/math&gt; for all &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;J_v = J \cap (\R \times v) \subseteq \R&lt;/math&gt; is an open interval &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt;, possibly infinite at one or both ends.
# If &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;t, s, t + s&lt;/math&gt; are in &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\alpha(t + s, v) = \alpha(t, \alpha(s, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

Secondly, it is clear that &lt;math display=&quot;inline&quot;&gt;\eta&lt;/math&gt; generates &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; because
# Each stratum &lt;math display=&quot;inline&quot;&gt;X&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; is invariant under &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt;, i.e. &lt;math display=&quot;inline&quot;&gt;\alpha[J \cap (\R \times X)] \subseteq X&lt;/math&gt;.
# For each &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;, the map &lt;math display=&quot;inline&quot;&gt;t \to \alpha(t, v)&lt;/math&gt; of &lt;math display=&quot;inline&quot;&gt;(a_v, b_v)&lt;/math&gt; into the stratum which contains &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; is &lt;math display=&quot;inline&quot;&gt;C^1&lt;/math&gt;.
# For any &lt;math display=&quot;inline&quot;&gt;(t, v) \in Z&lt;/math&gt;(?) we have &lt;math display=&quot;inline&quot;&gt;d/dt \alpha(t, v) = \eta(\alpha(t, v))&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

It is unique because each &lt;math display=&quot;inline&quot;&gt;(J_X, \alpha_X)&lt;/math&gt; is unique. We just need to prove that &lt;math display=&quot;inline&quot;&gt;J&lt;/math&gt; is open, &lt;math display=&quot;inline&quot;&gt;\alpha&lt;/math&gt; is continuous, and for any &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt; and any compact set &lt;math display=&quot;inline&quot;&gt;K \subseteq Z&lt;/math&gt; there exists &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\alpha(t, v) \notin K&lt;/math&gt; if &lt;math display=&quot;inline&quot;&gt;t \in (a_v, a_v + \epsilon) \cup (b_v - \epsilon, b_v)&lt;/math&gt;.&lt;ref&gt;Mather 2012, pp. 495.&lt;/ref&gt;

For the latter-most condition, if it did not hold then there exists...&lt;ref&gt;Mather 2012, pp. 496-497.&lt;/ref&gt;

We prove there is a homeomorphism &lt;math display=&quot;inline&quot;&gt;f: Z \to h^{-1}(0) \times \R&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;, where &lt;math display=&quot;inline&quot;&gt;\pi: h^{-1}(0) \times \R \to \R&lt;/math&gt; is projection to the second factor.

For the coordinate vector field &lt;math display=&quot;inline&quot;&gt;\partial&lt;/math&gt; on &lt;math display=&quot;inline&quot;&gt;\R&lt;/math&gt;, by [prop 9.1] there is a controlled vector field &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; such that &lt;math display=&quot;inline&quot;&gt;f_* \tilde\partial(v) = \partial(h(v))&lt;/math&gt; for &lt;math display=&quot;inline&quot;&gt;v \in Z&lt;/math&gt;. By [prop 10.1], &lt;math display=&quot;inline&quot;&gt;\tilde\partial&lt;/math&gt; generates a local one-parameter group &lt;math display=&quot;inline&quot;&gt;(J, \alpha)&lt;/math&gt; such that

&lt;math display=&quot;block&quot;&gt;h(\alpha(t,v)) = h(v) + t&lt;/math&gt;

&lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is proper and [d] holds, so &lt;math display=&quot;inline&quot;&gt;J = \R \times Z&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;f(v) = (\alpha(-t, v), h(v))&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; maps &lt;math display=&quot;inline&quot;&gt;Z&lt;/math&gt; into &lt;math display=&quot;inline&quot;&gt;h^{-1}(0) \times \R&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\pi \circ f = h&lt;/math&gt;. If we define &lt;math display=&quot;inline&quot;&gt;\bar f: h^{-1}(0) \times \R \to Z&lt;/math&gt; as

&lt;math display=&quot;block&quot;&gt;\bar f(v, t) = \alpha(t, v)&lt;/math&gt;

then &lt;math display=&quot;inline&quot;&gt;f \bar f = \bar f f = Id&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;f&lt;/math&gt; is a homeomorphism.&lt;ref&gt;Mather 2012, pp. 497.&lt;/ref&gt;

== Morse theory ==

Steps(?)
* Explain topology
* Every point of a stratum is locally like a product structure (proved by Thom's Isotopy Lemma) [GM pp. 41-42]
** Including those around critical points, which are the product of normal and tangential Morse data (these are our quasi-local cycles?)
* Thom's Isotopy Lemma proves a strong deformation retraction (which only stops at critical points) [PWM pp. 541-542]

=== Homotopy ===

We want to replace our domain of convergence &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt;, which is the complement of our singular variety &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;, with an &quot;equivalent&quot; space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; which has better understood properties. We say &quot;equivalent&quot; because there are several different things we could mean by &quot;equivalent&quot; in this context. The equivalence we are referring to in this section is called '''homotopy'''.

Imagine two subspaces &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; of a space &lt;math display=&quot;inline&quot;&gt;Y&lt;/math&gt; which are defined respectively by smooth functions &lt;math display=&quot;inline&quot;&gt;f, g: X \to Y&lt;/math&gt;. If there exists a smooth function &lt;math display=&quot;inline&quot;&gt;h_s: X \times [0, 1] \to Y&lt;/math&gt;, called a homotopy, such that &lt;math display=&quot;inline&quot;&gt;h_0 = f&lt;/math&gt;, &lt;math display=&quot;inline&quot;&gt;h_1 = g&lt;/math&gt; and for any &lt;math display=&quot;inline&quot;&gt;\epsilon &gt; 0&lt;/math&gt; there exists a &lt;math display=&quot;inline&quot;&gt;\delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\delta_b&lt;/math&gt; such that when &lt;math display=&quot;inline&quot;&gt;|s - s_0| &lt; \delta_a&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;|x - x_0| &lt; \delta_b&lt;/math&gt; we have &lt;math display=&quot;inline&quot;&gt;|h_s(x) - h_{s_0}(x_0)| &lt; \epsilon&lt;/math&gt;, then we say &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are '''homotopic'''.&lt;ref&gt;Henle 1979, pp. 251-252.&lt;/ref&gt;

Below is an example where &lt;math display=&quot;inline&quot;&gt;\gamma_0&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\gamma_1&lt;/math&gt; are one-dimensional curves and &lt;math display=&quot;inline&quot;&gt;H(t, s) = h_s(t)&lt;/math&gt;.

[[File:Homotopy_curves.png|300px]]

In [[#Homotopy_equivalence|Appendix A]], we formally prove that we can construct an equivalent space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt;. We provide only an example to give some intuition before describing how to construct the space &lt;math display=&quot;inline&quot;&gt;M'&lt;/math&gt; in terms of local cycles around critical points.

=== Motivating example ===

Imagine a torus and a height function which is just the z value of the point.

[[File:3D-Leveltorus.png|200px]]

It has four critical points: two at the top and bottom of the outer circle (&lt;math display=&quot;inline&quot;&gt;p_1, p_4&lt;/math&gt;) and two at the top and bottom of the inner circle (&lt;math display=&quot;inline&quot;&gt;p_2, p_3&lt;/math&gt;).

[picture]

When the height is between the &lt;math display=&quot;inline&quot;&gt;p_1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt;, the space is a two-cell, which can be retracted to a point.

[picture]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_2&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt;, the space is a cylinder, which can be retracted to a two-cell with a one-cell attached.

[[File:3D-Cylinder_and_disk_with_handle.png|200px]]

When the height is between &lt;math display=&quot;inline&quot;&gt;p_3&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, the space is a torus with a disc removed, which can be retracted to a cylinder with a one-cell attached.

[[File:3D-Cylinder_with_handle_and_torus_with_hole.png|200px]]

When the height is greater than &lt;math display=&quot;inline&quot;&gt;p_4&lt;/math&gt;, then the full torus is constructed by attaching a two-cell.

[Explain in terms of Morse data and Morse index?]

=== Morse data and quasi-local cycles ===

As in the above example, we start at the &quot;bottom&quot; of &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and build upwards until just before we reach our first critical point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.

;Smooth points
:This is a tube around a &lt;math display=&quot;inline&quot;&gt;(d-1)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; where the height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is maximised at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223.&lt;/ref&gt;
:For example, if &lt;math display=&quot;inline&quot;&gt;F(x, y) = \frac{1}{1 - x - y}&lt;/math&gt; then &lt;math display=&quot;inline&quot;&gt;\lambda = 1&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;B^\lambda&lt;/math&gt; is an arc reaching its highest point at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.
:The normal plane &lt;math display=&quot;inline&quot;&gt;N&lt;/math&gt; at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; is a plane orthogonal to &lt;math display=&quot;inline&quot;&gt;B^1&lt;/math&gt;(?).
:Its normal link &lt;math display=&quot;inline&quot;&gt;L(S)&lt;/math&gt; is a circle with two points missing where it intersects &lt;math display=&quot;inline&quot;&gt;\mathcal{V}&lt;/math&gt;.
:We make our quasi-local cycle out of the product of the arc and circle joined to &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt; at points below &lt;math display=&quot;inline&quot;&gt;M_-&lt;/math&gt;.
:With the exception of degenerate points, such as monkey saddles...&lt;ref&gt;e.g. Pemantle, Wilson and Melczer 2024, pp. 211.&lt;/ref&gt;

;Transverse multiple points
:This is the product of a &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-torus and a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;. The torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in the complex normal space to each strata which intersects &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;. The chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; is supported in the stratum which is the common intersection of the varieties defined by the factors vanishing at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;, and achieves its maximum height at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 223-224.&lt;/ref&gt;

;Arrangement multiple point
:This is the product of a &lt;math display=&quot;inline&quot;&gt;(d-k)&lt;/math&gt;-chain &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt; and several &lt;math display=&quot;inline&quot;&gt;k&lt;/math&gt;-tori, one for each pair of sheets which intersect transversely, where the torus is the product of circles about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in each sheet.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 226.&lt;/ref&gt;

;Cone point
:A cone point is zero-dimensional so there is no &lt;math display=&quot;inline&quot;&gt;\gamma&lt;/math&gt;, just a &lt;math display=&quot;inline&quot;&gt;d&lt;/math&gt;-torus about &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 227.&lt;/ref&gt;

== Appendix ==

=== Homotopy equivalence ===

[Assuming no CVAI...]

Theorem:
# Homotopy equivalence between M_{\leq a} and M_{\leq b}...
# If in a range &lt;math display=&quot;inline&quot;&gt;[a, b]&lt;/math&gt; there are no CVAI and only one critical value &lt;math display=&quot;inline&quot;&gt;c&lt;/math&gt;, not equal to either &lt;math display=&quot;inline&quot;&gt;a&lt;/math&gt; or &lt;math display=&quot;inline&quot;&gt;b&lt;/math&gt;, with one or more critical points &lt;math display=&quot;inline&quot;&gt;z_1, \cdots, z_m&lt;/math&gt; then there is a stratified flow deforming any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a (homotopic?) chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{&lt;c}&lt;/math&gt; with sufficiently small balls around each critical point. This induces a homotopy between &lt;math display=&quot;inline&quot;&gt;(M_{c+\epsilon}, M_{c-\epsilon})&lt;/math&gt; and the direct sum of &lt;math display=&quot;inline&quot;&gt;(M_{c-\epsilon} \cup B_{2\epsilon}(z_i), M_{c-\epsilon})&lt;/math&gt; for each critical point &lt;math display=&quot;inline&quot;&gt;z_i&lt;/math&gt;.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 231.&lt;/ref&gt;

The core of this is the concept of a '''vector field'''. A vector field is a function which assigns, for each point &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt; in a space, a '''vector''', which can be represented by an arrow whose tail starts at &lt;math display=&quot;inline&quot;&gt;p&lt;/math&gt;.&lt;ref&gt;Henle 1979, pp. 33.&lt;/ref&gt;

[picture]

Imagine we have a vector field &lt;math display=&quot;inline&quot;&gt;v(x)&lt;/math&gt; defined in a space and draw a line through our space. At each point along this line the vector field assigns a vector. If we move each point in this line along the arrow defined by this vector in the direction of the arrow head. This &quot;flows&quot; the entire line along the vectors.

We can (potentially) define a function to implement this flow. Define &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; are points in the space and &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; is something like time. As &lt;math display=&quot;inline&quot;&gt;t&lt;/math&gt; goes from zero to some positive number, &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; moves the points &lt;math display=&quot;inline&quot;&gt;x&lt;/math&gt; along the vectors. To describe this process formally, we say &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; is the solution to the differential equation

&lt;math display=&quot;block&quot;&gt;\frac{d}{dt} \Phi(x, t) = v(x).&lt;/math&gt;

We want a particular vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; with certain properties... The proof of the existence of this vector field is long and complicated and we will not go into it here.&lt;ref&gt;It involves concepts such as Thom's isotopy lemma and Mather's controlled vector flows. See Mather 2012.&lt;/ref&gt;

Using this vector field &lt;math display=&quot;inline&quot;&gt;v&lt;/math&gt; but modified so as to be zero on &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;. This vector field defines a function &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; such that
* &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t) = v(x)&lt;/math&gt; when &lt;math display=&quot;inline&quot;&gt;h(x) \in (a, b]&lt;/math&gt;.
* &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; is defined for &lt;math display=&quot;inline&quot;&gt;0 \leq t \leq h(x) - a&lt;/math&gt; and in this range &lt;math display=&quot;inline&quot;&gt;h(\Phi(x, t)) = h(x) - t&lt;/math&gt;.
* the map &lt;math display=&quot;inline&quot;&gt;\psi(x) = \Phi(x, b - a)&lt;/math&gt; is a continuous map on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; with range (image?) &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt; and fixing &lt;math display=&quot;inline&quot;&gt;M_{\leq a}&lt;/math&gt;.

The function &lt;math display=&quot;inline&quot;&gt;\Phi(x, 0)&lt;/math&gt; is the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\Phi(x, b - a) = \psi(x)&lt;/math&gt;, therefore &lt;math display=&quot;inline&quot;&gt;\Phi&lt;/math&gt; in the range &lt;math display=&quot;inline&quot;&gt;[0, b - a]&lt;/math&gt; is a homotopy between the identity on &lt;math display=&quot;inline&quot;&gt;M_{\leq b}&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;\psi&lt;/math&gt;. This implies 1)???&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 233.&lt;/ref&gt;

Define the distance from a critical point &lt;math display=&quot;inline&quot;&gt;\kappa(x) = \min\{ |x - z_i| : z_1, \cdots, z_m \}&lt;/math&gt;. For &lt;math display=&quot;inline&quot;&gt;s &gt; 0 &lt;/math&gt; we define a new vector field

&lt;math display=&quot;block&quot;&gt;v_s(x) = \begin{cases}
v(x) &amp; \kappa(x) \geq s \\
\rho(\kappa(x)) v(x) &amp; \kappa(x) \in [s/2, s] \\
0 &amp; \kappa(x) \leq s/2
\end{cases}&lt;/math&gt;

for a smooth non-decreasing function &lt;math display=&quot;inline&quot;&gt;\rho&lt;/math&gt; where &lt;math display=&quot;inline&quot;&gt;\rho(s/2) = 0&lt;/math&gt;.

Define &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; as the function such that &lt;math display=&quot;inline&quot;&gt;d/dt \Phi(x, t)_s = v_s(x)&lt;/math&gt;. The height function &lt;math display=&quot;inline&quot;&gt;h&lt;/math&gt; is non-increasing along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; (by implication of bullet point 2?) so points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; stay in &lt;math display=&quot;inline&quot;&gt;M_{\leq c - \epsilon}&lt;/math&gt; when flowed along &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; and therefore &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; is a homotopy equivalence between &lt;math display=&quot;inline&quot;&gt;(M_{\leq c+\epsilon}, M_{\leq c-\epsilon})&lt;/math&gt; and &lt;math display=&quot;inline&quot;&gt;(\Phi(M_{\leq c+\epsilon}, 2\epsilon), M_{\leq c-\epsilon})&lt;/math&gt;. By &lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; we mean the space &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; flowed along &lt;math display=&quot;inline&quot;&gt;\Phi(x, t)&lt;/math&gt; for a short period of time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

[Prove it has the same critical points and is proper?]

&lt;math display=&quot;inline&quot;&gt;\Phi(M_{\leq c+\epsilon}, 2\epsilon)&lt;/math&gt; takes points in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; except for those that come within &lt;math display=&quot;inline&quot;&gt;s&lt;/math&gt; of a critical point within time &lt;math display=&quot;inline&quot;&gt;2\epsilon&lt;/math&gt;.

Therefore, we see how we &lt;math display=&quot;inline&quot;&gt;\Phi_s&lt;/math&gt; can homotopically deform a chain in &lt;math display=&quot;inline&quot;&gt;M_{\leq c+\epsilon}&lt;/math&gt; to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{\leq c-\epsilon}&lt;/math&gt; and small neighbourhoods of critical points.&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 234-235.&lt;/ref&gt;

On the assumption of this theorem, we can start with any chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; and deform this chain to &lt;math display=&quot;inline&quot;&gt;M_{c_1+}&lt;/math&gt; using part 1. Then we deform this chain to a chain in the union of &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; and small balls around the critical points. The (sub?)chain in &lt;math display=&quot;inline&quot;&gt;M_{c_1-}&lt;/math&gt; is then deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2+}&lt;/math&gt;, which is deformed to a chain in &lt;math display=&quot;inline&quot;&gt;M_{c_2-} \cup z_{c_2}&lt;/math&gt;, and so on. Eventually, we get to &lt;math display=&quot;inline&quot;&gt;M_{c_j-}&lt;/math&gt; which is homotopic to any space &quot;below&quot; it. Therefore, we have deformed our chain in &lt;math display=&quot;inline&quot;&gt;M&lt;/math&gt; to a homotopic chain in the union of small balls around critical points.&lt;ref&gt;Baryshnikov, Melczer and Pemantle 2022, pp. ???.&lt;/ref&gt;&lt;ref&gt;Pemantle, Wilson and Melczer 2024, pp. 217???&lt;/ref&gt;

[Direct sum of homology generators for relative cycles]

== Notes ==
{{Reflist}}

== References ==
* {{citation | last1=Baryshnikov | first1=Yuliy | last2=Melczer | first2=Stephen | last3=Pemantle | first3=Robin | title=Stationary Points at Infinity for Analytic Combinatorics | year=2022 | journal=Foundations of Computational Mathematics | volume=22 | number=5 | pages=1631-1664 | url=https://www2.math.upenn.edu/~pemantle/papers/SPAI-published-version.pdf }}.
* {{cite book | last1=Goresky | first1=Mark | last2=MacPherson | first2=Robert | title=Stratified Morse Theory | publisher=Springer-Verlag | year=1988 | url=https://www.math.ias.edu/~goresky/pdf/SMT.djvu }}
* {{cite book | last=Henle | first1=Michael | title=A Combinatorial Introduction to Topology | publisher=Dover Publications Inc. New York | year=1979 }}
* {{citation | last=Mather | first=John | title=Notes on Topological Stability | year=2012 | journal=Bulletin of the American Mathematical Society | volume=49 | number=4 | pages=475-506 | url=https://www.ams.org/journals/bull/2012-49-04/S0273-0979-2012-01383-6/S0273-0979-2012-01383-6.pdf }}.
* {{cite book | last1=Pemantle | first1=Robin | last2=Wilson | first2=Mark C. | last3=Melczer | first3=Stephen | title=Analytic Combinatorics in Several Variables | publisher=Cambridge University Press | year=2024 | edition=2nd | url=https://acsvproject.com/PemantleWilsonMelczer23.pdf }}</text>
      <sha1>era8v6ovtjsnaiyvpjxolbfx5r0dbph</sha1>
    </revision>
  </page>
  <page>
    <title>Googology</title>
    <ns>0</ns>
    <id>481965</id>
    <revision>
      <id>4669862</id>
      <parentid>4627739</parentid>
      <timestamp>2026-09-13T09:12:01Z</timestamp>
      <contributor>
        <username>SHB2000</username>
        <id>3332924</id>
      </contributor>
      <minor />
      <comment>holy typos</comment>
      <origin>4669862</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3709" sha1="4t6003hx5j59ysl491xie5ia5krpghj" xml:space="preserve">{{Todo|Write Introduction.}}
{{status|0%}} {{shelves|Pure mathematics}} {{alphabetical|G}} {{reading level|advanced}} {{wikipedia}}

This book is about Googology, the study of large numbers. Readers are recommended to be familiar with basic arithmetic concepts, most importantly exponentiation. This book is for anyone who is unfamiliar with googological concepts such as notations and functions. The book is structured in a way that you have to read all previous sections in order to understand a section, so skipping sections is highly discouraged.

The book contains the fundamental notations in googology, such as the Fast-growing Hierarchy, Bird's Array Notation and the Bashicu Matrix System. A list of all googolisms (numbers relevant to googology) is available in the final section of the book.

== Table of Contents ==

* [[Googology/Cover|Cover]] 
* [[Googology/Introduction|Introduction]] 

=== Introduction to Googology {{stage short|0%|Mar 9, 2026}} ===

# [[Googology/What is Googology?|What is Googology?]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Difference Between Googology and Aritmetic|Difference Between Googology and Arithmetic]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Notations|Notations]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Functions|Functions]] {{stage|0%|Mar 9, 2026}}

=== Basic Googological Notations {{stage short|0%|Mar 9, 2026}} ===

# [[Googology/Powers of Ten and Scientific Notation|Powers of Ten and Scientific Notation]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Operations Greater Than Exponentiation|Operations Greater Than Exponentiation]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Bracket Notation|Bracket Notation]] {{stage|0%|Mar 9, 2026}}

=== Array Notations {{stage short|0%|Mar 9, 2026}} ===

==== BAN ====
# [[Googology/Linear Arrays|Linear Arrays]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Multidimensional Arrays|Multidimensional Arrays]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Hyperdimensional Arrays|Hyperdimensional Arrays]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Nested Arrays|Nested Arrays]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Beyond Nested Arrays|Beyond Nested Arrays]] {{stage|0%|Mar 9, 2026}}
## [[Googology/Beyond Nested Arrays/Part 1|Part 1]] {{stage|0%|Mar 9, 2026}}
## [[Googology/Beyond Nested Arrays/Part 2|Part 2]] {{stage|0%|Mar 9, 2026}}
## [[Googology/Beyond Nested Arrays/Part 3|Part 3]] {{stage|0%|Mar 9, 2026}}
## [[Googology/Beyond Nested Arrays/Part 4|Part 4]] {{stage|0%|Mar 9, 2026}}
## [[Googology/Beyond Nested Arrays/Part 5|Part 5]] {{stage|0%|Mar 9, 2026}}

==== SAN ====

# [[Googology/LAN|Linear Array Notation]]
# [[Googology/exAN|Extended Array Notation]]
# [[Googology/EAN|EAN]]
# [[Googology/mEAN|mEAN]]
# [[Googology/pDAN|Primary Dropping Array Notation]]
# [[Googology/sDAN|Secondary Dropping Array Notation]]
# [[Googology/DAN|Dropping Array Notation]]

=== Ordinals {{stage short|0%|Mar 9, 2026}} ===

# [[Googology/Introduction to Ordinals|Introduction to Ordinals]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Fast-Growing Hierarchy|Fast-Growing Hierarchy]] {{stage|0%|Mar 9, 2026}}
# [[Googology/FGH Extensions|FGH Extensions]]
# [[Googology/Other Hierarchies|Other Hierarchies]] {{stage|0%|Mar 9, 2026}}
# [[Googology/Hierarchies in Array Notation|Hierarchies in Array Notation]] {{stage|0%|Mar 9, 2026}}

=== BMS and Y-Sequence {{stage short|0%|Mar 9, 2026}} ===

# [[Googology/Bashicu Matrix System|Bashicu Matrix System]] {{stage|0%|Mar 9, 2026}}
# [[Googolpgy/DBMS|DBMS]]
# [[Googology/Y-Sequence|Y-Sequence]]
# [[Googology/Other Sequences|Other Sequences]]

* [[Googology/Glossary|Glossary]]
* [[Googology/List of Googolisms|List of Googolisms]]
* [[Googology/References|References]]
[[Category:Shelf:Pure mathematics]]</text>
      <sha1>4t6003hx5j59ysl491xie5ia5krpghj</sha1>
    </revision>
  </page>
  <page>
    <title>User:Sisterian/sandbox</title>
    <ns>2</ns>
    <id>485186</id>
    <revision>
      <id>4669760</id>
      <parentid>4659587</parentid>
      <timestamp>2026-09-12T13:51:39Z</timestamp>
      <contributor>
        <username>Sisterian</username>
        <id>3123918</id>
      </contributor>
      <comment>Created a toc</comment>
      <origin>4669760</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1242" sha1="shkv9yrktrax1ete3l2xcr97jlo1icy" xml:space="preserve">'''Sisterian''' as known on Wikipedia is a Ugandan social entrepreneur and website designer based in Kira Municipality, Uganda. He has a passion for social enterpreneurship and community development in health and education.


&lt;nowiki&gt;{{#invoke:table of contents|generate|Chapter 1|Chapter 1|This is Chapter 1. |100%&lt;/nowiki&gt;

'''GLAM Mentorship 2026: Wikibooks project'''

Phase 1: Conceptualization &amp; Vetting (The &quot;Why&quot;)

Step 1: Choose a Topic: Social media management

Step 2: Define your &quot;Reading Level - Adults

Step 3: Check for Existing Books

Step 4: Write a &quot;Book Shell&quot; Proposal

'''Book Summary'''

This Wikibook provides a comprehensive, step-by-step framework for developing, executing, and evaluating professional social media strategies across diverse organizational contexts—from small non-profits to multinational corporations. Designed for marketing practitioners, small business owners, and communication students, the book bridges theoretical communication models with actionable, platform-specific tactics.

Phase 2: Structural Blueprint (The &quot;How&quot;)

Title: Social media management

Introduction: Beyond the Post Buton


Chapters

Chapter 1: The Ethical Imperative

Chapter 2: The Social Dilema

Conclusion

References</text>
      <sha1>shkv9yrktrax1ete3l2xcr97jlo1icy</sha1>
    </revision>
    <revision>
      <id>4669762</id>
      <parentid>4669760</parentid>
      <timestamp>2026-09-12T13:52:52Z</timestamp>
      <contributor>
        <username>Sisterian</username>
        <id>3123918</id>
      </contributor>
      <origin>4669762</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1249" sha1="3tlstxa2xlfvr7hlo76872xfblch097" xml:space="preserve">'''Sisterian''' as known on Wikipedia is a Ugandan social entrepreneur and website designer based in Kira Municipality, Uganda. He has a passion for social enterpreneurship and community development in health and education.


&lt;nowiki&gt;{{#invoke:table of contents | generate | Chapter 1|Chapter 1|This is Chapter 1. |100% }}&lt;/nowiki&gt;

'''GLAM Mentorship 2026: Wikibooks project'''

Phase 1: Conceptualization &amp; Vetting (The &quot;Why&quot;)

Step 1: Choose a Topic: Social media management

Step 2: Define your &quot;Reading Level - Adults

Step 3: Check for Existing Books

Step 4: Write a &quot;Book Shell&quot; Proposal

'''Book Summary'''

This Wikibook provides a comprehensive, step-by-step framework for developing, executing, and evaluating professional social media strategies across diverse organizational contexts—from small non-profits to multinational corporations. Designed for marketing practitioners, small business owners, and communication students, the book bridges theoretical communication models with actionable, platform-specific tactics.

Phase 2: Structural Blueprint (The &quot;How&quot;)

Title: Social media management

Introduction: Beyond the Post Buton


Chapters

Chapter 1: The Ethical Imperative

Chapter 2: The Social Dilema

Conclusion

References</text>
      <sha1>3tlstxa2xlfvr7hlo76872xfblch097</sha1>
    </revision>
  </page>
  <page>
    <title>Wikibooks:Reading room/Administrative Assistance/Archives/2026/August</title>
    <ns>4</ns>
    <id>485284</id>
    <revision>
      <id>4669854</id>
      <parentid>4669645</parentid>
      <timestamp>2026-09-13T08:10:14Z</timestamp>
      <contributor>
        <username>ArchiverBot</username>
        <id>1227662</id>
      </contributor>
      <minor />
      <comment>Bot: Archiving 2 threads from [[Wikibooks:Reading room/Administrative Assistance]]</comment>
      <origin>4669854</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="8426" sha1="87jmr3glnp5vg65evnhd1n7xwalvrsl" xml:space="preserve">{{talk archive}}

== Permata55 reported by MathXplore ==

* {{userlinks|Permata55}}

Spam &lt;!-- USERREPORTED:/Permata55/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:33, 1 August 2026 (UTC)
: Already globally locked by a steward. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 20:23, 2 August 2026 (UTC)
== Birdsjungle reported by MathXplore ==

* {{userlinks|Birdsjungle}}

Link spam, [[Special:AbuseLog/314940]] &lt;!-- USERREPORTED:/Birdsjungle/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 11:21, 3 August 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 14:02, 3 August 2026 (UTC)
== Uniquehairgro reported by MathXplore ==

* {{userlinks|Uniquehairgro}}

Spam &lt;!-- USERREPORTED:/Uniquehairgro/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:37, 4 August 2026 (UTC)

:{{done}} —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 14:46, 4 August 2026 (UTC)
== Jerinjebin reported by MathXplore ==

* {{userlinks|Jerinjebin}}

Link spam, [[Special:AbuseLog/314965]] &lt;!-- USERREPORTED:/Jerinjebin/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 13:38, 5 August 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 15:39, 5 August 2026 (UTC)
== Nokiya23 reported by MathXplore ==

* {{userlinks|Nokiya23}}

Link spam, [[Special:AbuseLog/315040]] &lt;!-- USERREPORTED:/Nokiya23/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 11:36, 7 August 2026 (UTC)
: {{done}}. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 17:51, 7 August 2026 (UTC)
== Requesting temporary clearance to edit protected (content) namespace and template pages. ==

In order to continue to reduce the LintErrors, I'm requesting the temporary ability to edit protected pages in content and template namespaces.

I am requesting to do this under supervision of an adminstrator here, so a mentor experinced administrator is desirable.

A number of the remaining Lint issues concern specfic templates, which could have a considerable impact if the lint issues are resolved.&lt;br&gt; [[User:ShakespeareFan00|ShakespeareFan00]] ([[User talk:ShakespeareFan00|discuss]] • [[Special:Contributions/ShakespeareFan00|contribs]]) 18:26, 13 August 2026 (UTC)
: [[User:ShakespeareFan00|ShakespeareFan00]], in accordance with [[Wikibooks:Administrators#Temporary administrators]], please file a request at [[Wikibooks:Requests for permissions]]. State your reasons for requesting temporary adminship (such as the above), and please be aware that using the administrator permission for any admin action other than your stated task(s) may result in immediate removal by a steward. It will only be granted for the shortest duration as needed, so you may also want to state what time your permission should last as well. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 18:31, 13 August 2026 (UTC)
: @[[User:ShakespeareFan00|ShakespeareFan00]]—second ping. [[User:Codename Noreste|&lt;span style=&quot;color: blue&quot;&gt;Codename Noreste&lt;/span&gt;]] ([[User talk:Codename Noreste|discuss]] • [[Special:Contributions/Codename Noreste|contribs]]) 12:46, 14 August 2026 (UTC)
:: Noted,  It seems I might not need this after all. I seem to be making good progress as it is :) [[User:ShakespeareFan00|ShakespeareFan00]] ([[User talk:ShakespeareFan00|discuss]] • [[Special:Contributions/ShakespeareFan00|contribs]]) 14:36, 14 August 2026 (UTC)
== Flossandglosskidsdentistry reported by MathXplore ==

* {{userlinks|Flossandglosskidsdentistry}}

Spam &lt;!-- USERREPORTED:/Flossandglosskidsdentistry/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:50, 18 August 2026 (UTC)

:Seems to be globally locked! —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 17:22, 18 August 2026 (UTC)

== Solosfit reported by MathXplore ==

* {{userlinks|Solosfit}}

Spam &lt;!-- USERREPORTED:/Solosfit/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:51, 18 August 2026 (UTC)

:Seems to be globally locked. —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 17:22, 18 August 2026 (UTC)

== Mapcontechnologies reported by MathXplore ==

* {{userlinks|Mapcontechnologies}}

Spam &lt;!-- USERREPORTED:/Mapcontechnologies/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:51, 18 August 2026 (UTC)

:Seems to be globally locked. —[[User:Kittycataclysm|Kittycataclysm]] ([[User talk:Kittycataclysm|discuss]] • [[Special:Contributions/Kittycataclysm|contribs]]) 17:23, 18 August 2026 (UTC)
== IntoAEC reported by MathXplore ==

* {{userlinks|IntoAEC}}

Spam &lt;!-- USERREPORTED:/IntoAEC/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:25, 19 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:27, 26 August 2026 (UTC)

== CaribbeanMedicalSchools reported by MathXplore ==

* {{userlinks|CaribbeanMedicalSchools}}

Spam &lt;!-- USERREPORTED:/CaribbeanMedicalSchools/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:16, 26 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:27, 26 August 2026 (UTC)
== Chzoraiz41 reported by MathXplore ==

* {{userlinks|Chzoraiz41}}

Link spam, [[Special:AbuseLog/315229]] &lt;!-- USERREPORTED:/Chzoraiz41/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:09, 27 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 12:17, 27 August 2026 (UTC)
== Atlanticgym reported by MathXplore ==

* {{userlinks|Atlanticgym}}

Link spam, [[Special:AbuseLog/315249]] &lt;!-- USERREPORTED:/Atlanticgym/ --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 12:32, 29 August 2026 (UTC)

:{{done}} --[[User:SHB2000|SHB2000]] ([[User talk:SHB2000|discuss]] • [[Special:Contributions/SHB2000|contribs]]) 12:35, 29 August 2026 (UTC)
== Makowe2026 reported by Veritas Sapientiae ==

* {{userlinks|Makowe2026}}

Spam &lt;!-- USERREPORTED:/Makowe2026/ --&gt; [[User:Veritas Sapientiae|Veritas Sapientiae]] ([[User talk:Veritas Sapientiae|discuss]] • [[Special:Contributions/Veritas Sapientiae|contribs]]) 13:53, 29 August 2026 (UTC)

:{{done}} ―[[User:Koavf|Justin (&lt;span style=&quot;color:grey&quot;&gt;ko'''a'''&lt;span style=&quot;color:black&quot;&gt;v&lt;/span&gt;f&lt;/span&gt;)]]&lt;span style=&quot;color:red&quot;&gt;❤[[User talk:Koavf|T]]☮[[Special:Contributions/Koavf|C]]☺[[Special:Emailuser/Koavf|M]]☯&lt;/span&gt; 19:20, 29 August 2026 (UTC)</text>
      <sha1>87jmr3glnp5vg65evnhd1n7xwalvrsl</sha1>
    </revision>
  </page>
  <page>
    <title>User:AI For Beginners</title>
    <ns>2</ns>
    <id>485402</id>
    <revision>
      <id>4669758</id>
      <parentid>4665404</parentid>
      <timestamp>2026-09-12T13:39:14Z</timestamp>
      <contributor>
        <username>Sisterian</username>
        <id>3123918</id>
      </contributor>
      <minor />
      <comment>Sisterian moved page [[AI For Beginners]] to [[User:AI For Beginners]]</comment>
      <origin>4664823</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="990" sha1="9hfclgkimt57mk0dxo32bq7shu0begk" xml:space="preserve">{{qr-em|1=}}
{{formatting}}
== '''A FIELD GUIDE FOR TOTAL BEGINNERS''' ==

=== '''Charting the Unfamiliar Territory of AI''' ===
You don't need a maths degree or a computer-science background. You need a map. This book gives you one — plain language, real examples, and a route through machine learning, neural networks, and generative AI that starts wherever you're standing.

====  '''WHY THIS BOOK''' ====
Most AI books are written for people who already understand AI.
{| class=&quot;wikitable&quot; width=&quot;100%&quot;
|+
|-
| FIELD MARK 01
Plain terrain, not jargon
Every technical term is introduced through an everyday comparison before it's ever used on its own. No prior exposure assumed.
 || FIELD MARK 02
You try it as you go
Each chapter ends with a short, guided exercise using free tools — so the ideas stop being abstract by page 30.
 || FIELD MARK 03
Judgment, not hype
Honest coverage of what today's AI is genuinely good at, where it fails quietly, and how to tell the difference.

|}</text>
      <sha1>9hfclgkimt57mk0dxo32bq7shu0begk</sha1>
    </revision>
  </page>
  <page>
    <title>User:Makowe2026/sandbox/Social Media Management</title>
    <ns>2</ns>
    <id>485495</id>
    <revision>
      <id>4669764</id>
      <parentid>4668934</parentid>
      <timestamp>2026-09-12T14:40:38Z</timestamp>
      <contributor>
        <username>Makowe2026</username>
        <id>3620023</id>
      </contributor>
      <minor />
      <comment>No changes made</comment>
      <origin>4669764</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="19703" sha1="45028t50bcailwl62pibq3v0v0zjgdx" xml:space="preserve">== Table of content ==

== Introduction ==

===== What is Social Management =====
Social media management is the process of planning, creating, publishing, monitoring, and analyzing content across social media platforms to achieve specific business goals&lt;ref name=&quot;:0&quot;&gt;{{Cite web |title=What Is Social Media Management and How Does It Work? |url=https://mycontentbridge.ca/blog/what-is-social-media-management/ |access-date=2026-09-05 |website=mycontentbridge.ca |language=en}}&lt;/ref&gt;.

===== Overview of Major platforms =====
Social media management involves managing a brand’s presence on platforms such as Facebook, Instagram, LinkedIn, X, TikTok and others in a structured and strategic way&lt;ref name=&quot;:0&quot; details=&quot;[https://mycontentbridge.ca/blog/what-is-social-media-management/ blog/what-is-social-media-management/]&quot; /&gt;.

== Chapter 1: Defining your strategy ==

====== How to Identify Your Target Audience on Social Media ======
With the increasing popularity of social media, it’s becoming difficult to identify your target audience on specific platforms. This article shares tips on how you can identify your target audience on social media. 

&lt;nowiki&gt;{{&lt;/nowiki&gt;

You should start with finding out what your niche is. If you are a lifestyle blogger, for example, then you have a certain type of person in mind when you want to find your target audience. Identifying the niche will help you narrow down who these potential customers are and what their interests are.

This process will provide insights into what the future of social media looks like for different demographics. You can then use these insights to determine which platform is right for reaching your audience and which tools might be most effective at delivering this outcome&lt;ref name=&quot;:1&quot;&gt;{{Cite web |date=2022-02-05 |title=TIPS TO FIND YOUR TARGET AUDIENCE ON SOCIAL MEDIA |url=https://jelloow.com/blog-detail/6-tips-to-find-your-target-audience-on-social-media-platforms/ |access-date=2026-09-05 |language=en-US}}&lt;/ref&gt;.

====== Tips For Finding Your Target Audience on Social Media ======
Social media is vital for businesses that want to connect with their target market. However, identifying your target market can be a challenge because it is often hard to know who you are targeting.

So, how do you find your ideal customer on social media? Here are some tips for finding your target audience:

1) Identify the company/brand from their social media platform.

2) Determine who or what they love most on social media and see if they have a brand or product affiliation with them.

3) Look at what they’re talking about and who is responding to them on social media.

4) Find out what topics they’re posting about most frequently&lt;ref name=&quot;:1&quot; details=&quot;blog-detail/6-tips-to-find-your-target-audience-on-social-media-platforms/&quot; /&gt;.

====== How to Create Content That Appeals To The Right People &amp; Keeps People Engaged ======
Content that resonates with people’s interests and keeps them engaged is one of the essential factors for success. When creating content, it is important to consider what your target audience wants to hear about.

How does one know what their target audience wants to hear? You have to have a clear understanding of your audience. This can be done by asking questions, conducting surveys, or even just observing the behavior of your target audience.

The right content appeals to the right people and keeps them engaged in order to deliver a superior customer experience&lt;ref name=&quot;:1&quot; details=&quot;blog-detail/6-tips-to-find-your-target-audience-on-social-media-platforms/&quot; /&gt;.

== Chapter 2: Content Creation and Planning ==

=== Developing a brand voice and visual identity ===
When we think of a company or a brand, we refer to the combination of its physical, psychological and value-related characteristics. Just like a person, we can identify its overall appearance, recognizing it as related or unrelated to our own way of being. This recognition process is none other than the brand identity; the result of how the company decides to appear, communicate and relate to its audience&lt;ref name=&quot;:2&quot;&gt;{{Cite web |title=How to create a brand identity: from values, to tone of voice, to visual design |url=https://www.ied.edu/news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design |access-date=2026-09-05 |website=www.ied.edu}}&lt;/ref&gt;.

====== Defining brand identity values ======
Being able to create a brand identity that reflects the values of the brand means building a solid bridge between what the company wants to represent and its audience's perception. A well-defined identity not only increases brand recognition and consistency but also facilitates communication by reaching out directly to people who share the same values and principles.
Identifying the core values of brand identity is the crucial first step in building an authentic brand image. These values not only define the essence of the brand, but also shape all future decisions, from communication strategies to visual design.

The identification of the brand's core values begins with an internal process of analysis and brainstorming in which coherent ideas and themes for the core concepts are compiled. The ideas are then checked to see how they can become central pillars of the brand identity. In addition to the internal consultation phase, it is crucial to analyze and listen to what people say about the company, in order to identify the strengths and weaknesses of the brand, so that we can further build on them.

Once the values have been defined, it is essential to communicate them consistently and clearly in all present and future initiatives of the company. However, in order for the message to be authentic and true, it is necessary to devise a consolidated communication plan that includes tone of voice, design, and methods of interaction with the public&lt;ref name=&quot;:2&quot; details=&quot;[https://www.ied.edu/news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design]&quot; /&gt;.

====== Developing a signature tone of voice for brand identity ======
The tone of voice is not so much ''what'' the company says, but ''how'' it says it. It is the way the brand chooses to connect with people by communicating its story, values, and initiatives. To build an authentic brand identity, it is important to value the words and language used, to be able to compose coherent messages and establish an emotional connection between the brand and the target audience for the product or service.

Two elements have to be considered when setting the tone of voice: the target audience and the brand's value system. Analyzing the target audience is necessary in order to understand the needs and expectations of potential customers. If we are addressing a young target audience, for example, we can use more friendly and engaging language; a target group of experienced professionals will require more formal and technical language.  It is important not to lose sight of the brand identity in the tone of voice: it must be consistent with the values and personality of the company. A creative brand may adopt a fresh and lively language, while a brand based on loyal and traditional values should to communicate in a more reassuring and institutional way. Consistency between tone of voice and brand identity is essential when building authentic and credible communication&lt;ref name=&quot;:2&quot; details=&quot;[https://www.ied.edu/news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design]&quot; /&gt;.

====== Creating an appealing visual design of brand identity ======
In addition to the tone of voice, to effectively convey a brand identity it is crucial to study an appealing and innovative visual design. Elements such as the logo, colors, typography and images play a crucial role in defining the brand image and must be chosen carefully to reflect the company's personality and authenticity.

The logo, for example, should be distinctive but simple, capable of communicating the essence of the brand at first sight. Colors have a psychological impact and can evoke specific emotions or associations, while typography must be legible and consistent with the tone of voice of the brand. To strengthen the narrative and perception of the brand identity, the images used in communications should also be consistent with each other and in line with the brand message. Combining these elements into one harmonious and coherent design is essential to create a lasting and recognizable impression.

Applying a consistent visual brand identity

Consistency is the key to consolidating brand identity and ensuring maximum brand recognition across all communication channels, from physical channels such as shops and packaging, to digital channels such as websites and social platforms. Each element must be applied uniformly, maintaining the same color scheme and image style across all the different channels.

This framework helps build a recognizable identity and reinforces the brand's image in people's minds. It is therefore important to establish clear guidelines for the visual identity by ensuring that all employees understand and adhere to these guidelines while maintaining the integrity of the brand in different projects&lt;ref name=&quot;:2&quot; details=&quot;[https://www.ied.edu/news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design /news/how-to-create-a-brand-identity-from-values-to-tone-of-voice-to-visual-design]&quot; /&gt;.

====== Monitoring and adapting brand identity ======
Monitoring the effectiveness of brand identity over time is crucial to ensure that it continues to reflect brand values and audience needs. Gathering consumer feedback, analysing the performance of marketing campaigns and observing industry trends is key to assessing whether the brand identity remains relevant and effective or needs some changes.
Shifts in the market or in the strategic orientation of the company may require adjustments and updates in the visual design or tone of voice. An ongoing process of evaluating and adapting these elements helps to keep the brand identity consistent, up-to-date and well-connected to the public.

It is also important to monitor the competition to understand how competitor brand identities evolve. This will help to identify opportunities for differentiation. Analysing  social media engagement performance, customer reviews and sales data can provide further insight into how the brand is perceived and which areas might need improvement. Finally, periodically involving employees and corporate partners in the brand identity review process can provide valuable internal insights and ensure that everyone is aligned with the evolution of the brand.

== Chapter 3: Publishing and Automation ==

==== Best Time to Post on Different Platforms ====
The right social media post at the wrong time can feel invisible. You may have strong visuals, a clear message, or even the perfect hook—but if your audience isn’t online, it’s easy for it to slip past unnoticed.

This is why knowing the best time to post matters. Different platforms operate at different rhythms, and in Singapore, those patterns don’t always align with global averages. Add in algorithms that reward fresh engagement, and choosing when to post becomes one of several ways to give your content a better chance. There isn’t a single best time for everyone. Your audience, their routines, and the type of content you share all play a role. But paying attention to common peaks and avoiding the dead zones can tilt things in your favor and help your posts reach the people you want, when they’re most ready to engage. Here’s a summary of the topics we’ll be discussing:

* There is no universal “best time” to post — your optimal timing depends on your audience’s daily routines, locations, and content preferences.
* In 2025, algorithms prioritize early engagement, watch time, saves, and meaningful interactions, making timing a key amplifier for visibility.
* Singapore audiences generally peak during midday and evening, but each brand must verify its ideal windows through native analytics and consistent testing.
* AI tools such as Later, Metricool, and Publer now recommend personalized posting times based on real engagement data.
* Strong timing only boosts reach — the real driver of performance is valuable, people-first content that aligns with audience needs.
* The article provides a full breakdown of the best posting times for every major platform, plus strategies to analyze, test, and refine your own posting schedule&lt;ref&gt;{{Cite web |last=Lim |first=Walter |date=2025-12-23 |title=Best Time to Post on Social Media: Platform Breakdown |url=https://www.equinetacademy.com/blog/best-time-to-post-on-social-media-platform-breakdown/ |access-date=2026-09-05 |website=Equinet Academy |language=en-US}}&lt;/ref&gt;.

==== Best Practices for Cross-posting Content ====
It’s a big pet peeve of mine to check out a brand’s social media profiles and see that their accounts are just lazily connected. Please don’t do this. Instead use a scheduling tool like Hootsuite or AgoraPulse to set up your cross- posting correctly.

Once you’re in the grove of things, you can step up your cross-posting game, and use each network to your advantage.

Here’s how.

=== 1. Learn The Language Of Each Social Media Network ===
Before you start cross-posting content, you first need to learn how each individual social network operates, and it’s unique capabilities and functions.

Learn all the network specific tools you have available to use. You’ll need to figure this out in order to decide how you can optimize each post for each network, and/or how you can make your individual post work on each. We’ll get into more details about this later in this post&lt;ref name=&quot;:3&quot;&gt;{{Cite web |title=Best Practices for Cross-Posting on Social Media Correctly {{!}} Social Media Today |url=https://www.socialmediatoday.com/news/best-practices-for-cross-posting-on-social-media-correctly/519706/ |access-date=2026-09-05 |website=www.socialmediatoday.com |language=en}}&lt;/ref&gt;.

=== 2. Does The Post Belong On This Channel? ===
Not every post will work on every social platform – and that’s okay.

Take your overall strategy and your network strategy into consideration. You should also take the tone of the network into consideration.

For example, if you’re doing a fun, behind the scenes post of your team’s lunch spread, it might not make sense to post a picture to your company’s LinkedIn page - but it could be great content for Instagram, or even your brand’s Instagram Story.

This also gives you the opportunity to get a little creative if you do want to post the same content on each network, more about that in the next section&lt;ref name=&quot;:3&quot; details=&quot;[https://www.socialmediatoday.com/news/best-practices-for-cross-posting-on-social-media-correctly/519706/ news/best-practices-for-cross-posting-on-social-media-correctly/519706/]&quot; /&gt;

=== 3. Optimize Content For Each Network ===
Once you’re familiar with how each of the networks you’re posting to functions, you’ll want to optimize the content you’re cross-posting for each specific network.

Keep up with the story. Subscribe to the Social Media Today free daily newsletter

This is where the steps we just talked about come in handy - you can transform each post to work with the network you’re posting to, giving you an opportunity to flex your creative skills and use those network specific tools to make your posts more dynamic and show your audience you know what you’re doing.

Some posts will be fine to keep mostly the same with small tweaks. This includes shortening or lengthening captions to meet character limits, adding or taking away hashtags, and playing with wording. For example, you may post longer captions on LinkedIn or Facebook and shorter ones on Twitter.

Other posts will be complete revamps, taking into account which network/s they’ll be posted to, and this is where you can take advantage of network specific tools.

In the example below I’m asking my followers to join my list. With my tweet, I’ve used a Twitter Card, while on Facebook I went with an image and a link within the caption (I also changed the wording a little).

Take into consideration which formats work best on each network, and for your audience as well.

For example, I work with a client who’s Facebook Page audience reacts well to links (and they wanted to keep their Facebook as a resource for links to content). So when we post a blog article on Facebook, and we think it’s information we’d also like to share on Instagram, we have to adjust. We pull key stats from the post, and include them in our caption as a synopsis of the article we post on Facebook.

It’s the same piece of content, we just tweak our delivery to match the network format and language&lt;ref name=&quot;:3&quot; details=&quot;[https://www.socialmediatoday.com/news/best-practices-for-cross-posting-on-social-media-correctly/519706/ news/best-practices-for-cross-posting-on-social-media-correctly/519706/]&quot; /&gt;.

=== 4. Schedule According To Each Network’s Peak Time ===
The last consideration of proper cross-posting on social media is to schedule posts for the individual peak times on each social media network - and again, relative to your unique audience on each.

This will ensure you’re posting when the most amount of people will see it, per network, maximizing your opportunities for success.

Hopefully these steps will help you get a little more dynamic with your cross-posting on social media, and avoid the seemingly time-saving trap of simply automating your tweets to post to Facebook, or your Instagram Stories content to cross over to Facebook Stories (note: Facebook Stories don’t allow links, so links you post in your Instagram Stories won’t work)&lt;ref name=&quot;:3&quot; details=&quot;[https://www.socialmediatoday.com/news/best-practices-for-cross-posting-on-social-media-correctly/519706/ news/best-practices-for-cross-posting-on-social-media-correctly/519706/]&quot; /&gt;.

== Chapter 4: Paid Social Media Advertising ==

==== What Is Paid Social Advertising? ====
'''Paid social advertising''' is when businesses pay social media platforms to show their content to a targeted audience. Unlike organic posts (which rely on the algorithm’s mercy), paid social gives you guaranteed visibility. Whether you’re aiming to build brand awareness, drive traffic, or convert leads into customers, paid social is your shortcut to scalable results&lt;ref name=&quot;:4&quot;&gt;{{Cite web |title=What is Paid Social Advertising: A Complete Guide &gt; One Day Agency |url=https://oneday.agency/blog/paid-social-advertising |access-date=2026-09-05 |website=One Day Agency: Integrated Advertising and Marketing Agency |language=en-GB}}&lt;/ref&gt;.

==== Types of Paid Social Ads ====
You’ve definitely seen these—whether you knew it or not:

* '''In-Feed Ads''': Look like regular posts, but marked as “Sponsored.”
* '''Image Ads''': A strong image + a compelling call-to-action.
* '''Video Ads''': Great for storytelling or showcasing your product in action.
* '''Carousel Ads''': Multiple images or videos you can swipe through.
* '''Boosted Posts''': Extend the reach of high-performing organic content&lt;ref name=&quot;:4&quot; details=&quot;blog/paid-social-advertising&quot; /&gt;.

== Appendix / Resources ==

===== Glossary of social media terms =====

===== Recommended tools and software =====

===== Further reading and contributor guidelines =====</text>
      <sha1>45028t50bcailwl62pibq3v0v0zjgdx</sha1>
    </revision>
  </page>
  <page>
    <title>Electric Tractor</title>
    <ns>0</ns>
    <id>485500</id>
    <revision>
      <id>4669783</id>
      <parentid>4669230</parentid>
      <timestamp>2026-09-12T22:09:36Z</timestamp>
      <contributor>
        <username>~2026-49360-40</username>
        <id>3625812</id>
      </contributor>
      <comment>E</comment>
      <origin>4669783</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3761" sha1="glgdipd6bmk441ewnn0ypmy9tmzm3g8" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle</text>
      <sha1>glgdipd6bmk441ewnn0ypmy9tmzm3g8</sha1>
    </revision>
    <revision>
      <id>4669784</id>
      <parentid>4669783</parentid>
      <timestamp>2026-09-12T22:16:31Z</timestamp>
      <contributor>
        <username>Supermannevermadeanymoney</username>
        <id>3610439</id>
      </contributor>
      <origin>4669784</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="3904" sha1="4l7h00mqx8q7m0cb4s3flnj5tjdgw7i" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle and diode on the contactor coil which prevents current flow in reverse direction on the power input of the controller

[[File:KellyMotor.jpg]]</text>
      <sha1>4l7h00mqx8q7m0cb4s3flnj5tjdgw7i</sha1>
    </revision>
    <revision>
      <id>4669785</id>
      <parentid>4669784</parentid>
      <timestamp>2026-09-12T22:26:41Z</timestamp>
      <contributor>
        <username>Supermannevermadeanymoney</username>
        <id>3610439</id>
      </contributor>
      <origin>4669785</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="4395" sha1="72mfndzd7jvvt5dbvowhvpymr5vpqx3" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle and diode on the contactor coil which prevents current flow in reverse direction on the power input of the controller

[[File:KellyMotor.jpg]]

In practice the circuit that runs the motor had two important glitches, first was proper electrical crimps, the kelly contoller connects are

automotive connectors '''they should be crimped by having the wire at the first set of tongs and the bare wire at the second, the covered wire secures the crimp in place and the bare wire connects.  One of the connectors is currently partially loose and should be plug and secured tightly to start up the tractor.  This will need to be changed.'''</text>
      <sha1>72mfndzd7jvvt5dbvowhvpymr5vpqx3</sha1>
    </revision>
    <revision>
      <id>4669786</id>
      <parentid>4669785</parentid>
      <timestamp>2026-09-12T22:35:09Z</timestamp>
      <contributor>
        <username>Supermannevermadeanymoney</username>
        <id>3610439</id>
      </contributor>
      <origin>4669786</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="5149" sha1="dw8jmohy345rs1r29yzyww8q15vgk23" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle and diode on the contactor coil which prevents current flow in reverse direction on the power input of the controller

[[File:KellyMotor.jpg]]

In practice the circuit that runs the motor had two important glitches, first was proper electrical crimps, the kelly contoller connects are

automotive connectors '''they should be crimped by having the wire at the first set of tongs and the bare wire at the second, the covered wire secures the crimp in place and the bare wire connects.  One of the connectors is currently partially loose and should be plug and secured tightly to start up the tractor.  This will need to be changed.'''

The motor itself is connected to the gearbox by an adaptor plate, the motor driveshaft should be centered on the bearing exactly, this is tricky if you try as I did to line up the holes with measurement of the bolt holes, what worked was to machine the motor coupler to fit between the bearing and the motor shaft thus perfectly centering the plate.  The motor is bolted to the plate by machining a square hole in the plate with the milling machine sufficienty wide to accomodate the motor shaft bolting the motor to the plate,  the alignment occurs by aligning the plate to the gearbox pretty much at any angle but square is sastifying.  '''Because the electronics are currently too close to the ground a new adaptor plate will need to be machined.'''</text>
      <sha1>dw8jmohy345rs1r29yzyww8q15vgk23</sha1>
    </revision>
    <revision>
      <id>4669787</id>
      <parentid>4669786</parentid>
      <timestamp>2026-09-12T22:48:56Z</timestamp>
      <contributor>
        <username>Supermannevermadeanymoney</username>
        <id>3610439</id>
      </contributor>
      <origin>4669787</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="5901" sha1="6yj4y8acaa0pzlctva1b3z6u5lfkbvl" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle and diode on the contactor coil which prevents current flow in reverse direction on the power input of the controller

[[File:KellyMotor.jpg]]

In practice the circuit that runs the motor had two important glitches, first was proper electrical crimps, the kelly contoller connects are

automotive connectors '''they should be crimped by having the wire at the first set of tongs and the bare wire at the second, the covered wire secures the crimp in place and the bare wire connects.  One of the connectors is currently partially loose and should be plug and secured tightly to start up the tractor.  This will need to be repeated all connections are secure.'''

The motor itself is connected to the gearbox by an adaptor plate, the motor driveshaft should be centered on the bearing exactly, this is tricky if you try as I did to line up the holes with measurement of the bolt holes, what worked was to machine the motor coupler to fit between the bearing and the motor shaft thus perfectly centering the plate.  The motor is bolted to the plate by machining a square hole in the plate with the milling machine sufficienty wide to accomodate the motor shaft bolting the motor to the plate,  the alignment occurs by aligning the plate to the gearbox pretty much at any angle but square is sastifying.  '''Because the electronics are currently too close to the ground a new adaptor plate will need to be machined with the plate to the side.  Motor connections need to contained with a sock that is sewed.\'''

Battery Frame

The frame was built in a bit of slipshod manner by bolting together.  A key idea is to have battery swap allowing for extended work times by swapping batteries.  The current situation is a 15 amp charger that can charge the 100 ah battery in ~ 7 hours a level '''a 32 amp level 2 charger could be installed on farmships current electrical system''', this would allow for full charge in just over three hours, a system like this could also charge 4 batteries on an overnight charge that would allow for 4 hours of working time during the day. It would be possible to carry '''two batteries''' on the tractor at once.</text>
      <sha1>6yj4y8acaa0pzlctva1b3z6u5lfkbvl</sha1>
    </revision>
    <revision>
      <id>4669788</id>
      <parentid>4669787</parentid>
      <timestamp>2026-09-12T22:52:26Z</timestamp>
      <contributor>
        <username>Supermannevermadeanymoney</username>
        <id>3610439</id>
      </contributor>
      <origin>4669788</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="6085" sha1="k2k3h43n8u5vmzmb08pnwg1t3nlxx04" xml:space="preserve">

This page is for the BCS 201 Electric Rototiller made for Farmship Growers Cooperative/Haliburton Community Organic Farm.

The design of the tiller system was inspired by Reid Allaway of Tournesol cooperative, Reid runs the DIY electric farmer facebook group, that is a good place to find out about electric tractors.

The system is based around the following information

The motor, the motor is permanent magnet synchronous machine motor ME1509 from Motoenergy, an american company. PMSM are highly efficient when run at the correct RPM and torque, the diagram for the me1509 is not available though this one form the me1507 shows the idea

https://www.thunderstruck-ev.com/images/companies/1/ME1507dyno.pdf?1518651550248

the me1507 when run at 5000 rpm would be 100% efficient meaning that electrical power inputed would be fully applied as output power at the shaft.

The BCS 201 has a reduction gear box, 12:75 or ~ 7:1 reduction.  The output RPM for a tiller should be about 540 rpm so with a 7:1 gear ratio 3780.  I.e. the motor used should have high efficiency at 3780 RPM the motenergy 1509 is efficient in the range of 2500-3500 rpm so an ideal motor.

The power of the motor is determined by how much heat it can disappate as well as the input power.  In theory since the windings of a motor are low resistance you can put as much energy into the motor as you would like, but it shouldn't overheat and melt the windings.  So the motor power is essentially power in keeping in mind the rate at which the motor dissapates energy.  So when making garden beds, check that the motor is not above ~70 C.   It should feel warm but not feel like it is burning.  It is possible to put a cycleanalyst display on the motor that can read the motor temperature as their is a sensor in the motor.

The battery for the electric tractor should output sufficent power to provide the necessary torque for doing the job at the tines.  The gas motors on rototillers are typically 5-10 hp, a 5000 watt motor will output approximately 5.6 hp so in the correct range.  At 3600 rpm the torque of 5000 watts motor (torque = power/RPM) is 13Nm, with the 7:1 reduction gear and an efficiency factor of .8 72.8Nm so in theory the 5kw motor will deliver the torque required.  Reid Allaway designed a similar tiller and found that the motor was adequate to do the job with a kelly motor controller that delivers peak amps of 200.   So a 48 volt battery (potential) with 100 ah (capacity) that can run at 2C (rate) will deliver 4000-8000 watts of power to the motor drive shaft (efficiency factor of .8 included)

The motor controller used in this project is a Cheetah motor controller.  It is sinuoisdal brushless DC motor controller meaning it works from a computerized programming detecting the magnetic fields of the motor and not using commutator brushes.  The control circuit is  relatively simple as outlined  

[https://media.kellycontroller.com/new/Kelly-Cheetah-series-KLS-SUserManual.pdf Kelly Cheetah Motor Controller Guide]

you can see on page 13 of the manual the circuit for connecting the motor controller to the motor

Important elements are a 200 amp fuse on the positive line of the controller that prevents overcurrent.  The next element is a contactor that is has a coil that closes the circuit to the battery this is then connected to the battery pack and on the negative side of the pack to the low voltage..  The positive of the patter pack is also connected to a key witch then when closed powers the controller as well as the contactor coil.  There's also the hall sensor connections to the motor which are the power, the three sensor signals and the ground.  Their is a directional switch which is determines the direction of the motor and a throttle and diode on the contactor coil which prevents current flow in reverse direction on the power input of the controller

[[File:KellyMotor.jpg]]

In practice the circuit that runs the motor had two important glitches, first was proper electrical crimps, the kelly contoller connects are

automotive connectors '''they should be crimped by having the wire at the first set of tongs and the bare wire at the second, the covered wire secures the crimp in place and the bare wire connects.  One of the connectors is currently partially loose and should be plug and secured tightly to start up the tractor.  This will need to be repeated all connections are secure.'''

The motor itself is connected to the gearbox by an adaptor plate, the motor driveshaft should be centered on the bearing exactly, this is tricky if you try as I did to line up the holes with measurement of the bolt holes, what worked was to machine the motor coupler to fit between the bearing and the motor shaft thus perfectly centering the plate.  The motor is bolted to the plate by machining a square hole in the plate with the milling machine sufficienty wide to accomodate the motor shaft bolting the motor to the plate,  the alignment occurs by aligning the plate to the gearbox pretty much at any angle but square is sastifying.  '''Because the electronics are currently too close to the ground a new adaptor plate will need to be machined with the plate to the side.  Motor connections need to contained with a sock that is sewed.\'''

Battery Frame

The frame was built in a bit of slipshod manner by bolting together.  A key idea is to have battery swap allowing for extended work times by swapping batteries.  The current situation is a 15 amp charger that can charge the 100 ah battery in ~ 7 hours a level '''a 32 amp level 2 charger could be installed on farmships current electrical system''', this would allow for full charge in just over three hours, a system like this could also charge 4 batteries on an overnight charge that would allow for 4 hours of working time during the day. It would be possible to carry '''two batteries''' on the tractor at once. '''The comment was the center of mass of the tractor was too high.  Rotating the battery 90 degrees would help or two batteries on either side of the tractor would also be possible'''</text>
      <sha1>k2k3h43n8u5vmzmb08pnwg1t3nlxx04</sha1>
    </revision>
  </page>
  <page>
    <title>Maxima/Programming</title>
    <ns>0</ns>
    <id>485506</id>
    <revision>
      <id>4669757</id>
      <parentid>4669731</parentid>
      <timestamp>2026-09-12T13:33:45Z</timestamp>
      <contributor>
        <username>Idavidmiller</username>
        <id>3577687</id>
      </contributor>
      <comment>Work in progress. Saving Changes.</comment>
      <origin>4669757</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="7942" sha1="g3h0ixx5ho6cfahn9gs6rmpxsxzyslx" xml:space="preserve">=Maxima Programming=
Although Maxima is not a general-purpose programming language, Maxima as a CAS includes among the built-in ingredients a relatively complete set of programming expressions that are useful for the intended context. Many of the code examples of this section are intended to be illustrative of technical details relevant to Maxima programming as their purpose, and consequently are intentionally elementary in character.

Learning any sort of programming language, including Maxima programming expressions, is a subjective process. In any case, it is essential to have enough technical know-how specific to the programming language in order to begin the learning process, even in cases where much positive transfer from other programming experience is involved.

Much can be accomplished mathematically using Maxima without having to resort to in-depth knowledge and proficiency in the technical details of Maxima programming expressions. However, Maxima programming expressions are frequently essential for the purpose of defining functions, both in the programming sense of the term, but also more relevantly, to the mathematical sense. For that reason alone, familiarity and sufficient proficiency with Maxima programming expressions should be given some attention.

One way to begin the learning process is to become familiar with enough of the programming essentials to accomplish independent efforts toward accomplishing some specific programming goal of interest.  The other way is to study the many available programming expressions of others. This section is intended to provide the essentials toward learning by whatever means is chosen.

The following table shows some built-in ingredients related to Maxima programming expressions:
{| class=&quot;wikitable&quot;
|+Maxima Programming Category
|if
|unless
|errcatch
|prederror
|-
|block
|for
|error
|return
|-
|catch
|from
|warning
|throw 
|-
|local
|thru
|errormsg
|sstatus
|-
|garbage_collect
|step
|errormsg
|status
|-
|do
|next
|go
|
|-
|while
|in
|
|
|}

Some of these programming expression ingredients can also be considered as belonging to one or more other categories than the Programming category.

=== Block Expressions ===
Arguably, the first expressions to consider in the context of Maxima programming are '''''block''''' expressions. Block expressions as programming ingredients come in two flavors:

* &lt;code&gt;( expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt; )&lt;/code&gt;
* &lt;code&gt;block ([v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;], expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;)&lt;/code&gt;

The first form of a block expression is equivalent to the second form, but without the first list argument: &lt;code&gt;[v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;]&lt;/code&gt;, as in &lt;code&gt;block (expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;, unless &lt;code&gt;return&lt;/code&gt; or &lt;code&gt;go&lt;/code&gt; are used in the block expression. In that, case the form &lt;code&gt;block (expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;)&lt;/code&gt; must be used.

The purpose of the list argument,  &lt;code&gt;[v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;]&lt;/code&gt; is to declare the values of identifiers of the list to be local to the &lt;code&gt;block&lt;/code&gt;. If there is no need for local identifiers, the list argument can be omitted, unless &lt;code&gt;return&lt;/code&gt; or &lt;code&gt;go&lt;/code&gt; are used in the &lt;code&gt;block&lt;/code&gt; expression, and either form is sufficient.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;/* This block expression */
(%i1)	(x : 2, x^2);
(%o1)	4

/* Is equivalent to this block expression */
(%i2)	block (x : 2, x^2);
(%o2)	4&lt;/syntaxhighlight&gt;So, in the case where values of identifiers local to the &lt;code&gt;block&lt;/code&gt; of expressions are not required, then the choice of either form of the &lt;code&gt;block&lt;/code&gt; expression is a matter of user preference, . In both cases, the values of identifiers referenced in the &lt;code&gt;block&lt;/code&gt; are global, and not local to the &lt;code&gt;block&lt;/code&gt;.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
/* The value 3 assigned to x is global */
(%i3)	x : 3;
(x)	    3

/* The value 2 assigned to x in the block is global */
(%i4)	(x : 2, x^2);
(%o4)	4

/* The global value assigned to x in the block is 2 not 3 */
(%i5)	x;
(%o5)	2
&lt;/syntaxhighlight&gt;Values of identifiers local to the &lt;code&gt;block&lt;/code&gt; may not be global:&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;/* the value of identifier y is local only */
(%i6)	block ([y], y : 4, y);
(%o6)	4

/* the global value of identifier y is not 4, but is itself */
(%i7)	y;
(%o7)	y

/* the values of identifiers x and y are both local */
(%i8)	block ([x,y], x : 3, y : 4, x);
(%o8)	3

/* the global value of identifier x is not 3, but is 2 */
(%i9)	x;
(%o9)	2

/* the global value of identifier y is not 4, but is itself */
(%i10)	y;
(%o10)	y&lt;/syntaxhighlight&gt;

Regardless of the form of the &lt;code&gt;block&lt;/code&gt; expressions these have in common the comma-separated expression arguments &lt;code&gt;expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;  which are evaluated each in turn from first to last (unless the evaluation sequence is modified by by the &lt;code&gt;go&lt;/code&gt;, &lt;code&gt;throw&lt;/code&gt;, or &lt;code&gt;return&lt;/code&gt; operators), and the value of the block expression is the value of  &lt;code&gt;expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;. 

The main purpose of the &lt;code&gt;block&lt;/code&gt; expression, regardless of the form, it to group expressions that are related in some manner, and the value of the last expression may be the only value of interest. However, there are very few limitations imposed on the nature of the &lt;code&gt;block&lt;/code&gt; expression arguments, so it might be the case that the purpose of evaluating the &lt;code&gt;block&lt;/code&gt; expression has been achieved before the last expression argument is evaluated, in which case the value of the &lt;code&gt;block&lt;/code&gt; expression may not necessarily be the value of the last argument expression.

One way to accomplish that is to use an empty string as the last argument expression with the option flag &lt;code&gt;stringdisp&lt;/code&gt;set to &lt;code&gt;false&lt;/code&gt; which is the default value.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i11)	stringdisp;
(%o11)	false

(%i12)	block ([x,y], x : 3, y : 4, x, &quot;&quot;);
(%o12)	

(%i13)	block ([x,y], x : 3, y : 4, x)$
&lt;/syntaxhighlight&gt;
The display of the value of the &lt;code&gt;block&lt;/code&gt; expression may be suppressed using a &lt;code&gt;$&lt;/code&gt; to end the input expression instead of a semi-colon. Either technique produces a &lt;code&gt;block&lt;/code&gt; expression value, but the value is not displayed. If a &lt;code&gt;return&lt;/code&gt; operator is evaluated as a argument expression, this will cause evaluation of expression arguments to end explicitly, and the value of the &lt;code&gt;return&lt;/code&gt; operator becomes the value of the &lt;code&gt;block&lt;/code&gt; expression.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i14)	is (equal (x,2));
(%o14)	true

%i15)	block (if is (equal (x,2)) then return (x), &quot; x not 2&quot;);
(%o15)	2

(%i16)	x : 3;
(x)	3

(%i17)	block (if is (equal (x,2)) then return (x), &quot;x not 2&quot;);
(%o17)	x not 2
&lt;/syntaxhighlight&gt;One way to modify the first-to-last evaluation sequence of a bock expression is by way of a go operator with a label argument ( &quot;a go to loop&quot;) as the following exemplifies:&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i18)	sum_to_n (n) := block ( [i : 1, total : 0],
	                             loop,
	                                total : total + i,
	                                i : i + 1,
	                                if i &lt;= n then go (loop),
	                             total)$

(%i19)	sum_to_n(25);
(%o19)	325

(%i20)	n;
(%o20)	n

(%i21)	i;
(%o21)	i

(%i22)	total;
(%o22)	total
&lt;/syntaxhighlight&gt;How It Works

* block([i: 1, total: 0], ...): Creates a local environment with local variables i and total.
* loop: Acts as a target tag inside the block where go() can jump.
* if i &lt;= n then go(loop): Jumps back to the loop tag if the condition is true.
* total: Returns the final accumulated value when the loop finishes

=== Functions ===

=== Lisp and Maxima ===

{{BookCat}}</text>
      <sha1>g3h0ixx5ho6cfahn9gs6rmpxsxzyslx</sha1>
    </revision>
    <revision>
      <id>4669795</id>
      <parentid>4669757</parentid>
      <timestamp>2026-09-13T02:45:58Z</timestamp>
      <contributor>
        <username>Idavidmiller</username>
        <id>3577687</id>
      </contributor>
      <comment>Work in progress. Saving Changes.</comment>
      <origin>4669795</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="8590" sha1="2iu2j4ezxxzyvu0kt7z2hf2fr32qysc" xml:space="preserve">=Maxima Programming=
Although Maxima is not a general-purpose programming language, Maxima as a CAS includes among the built-in ingredients a relatively complete set of programming expressions that are useful for the intended context. Many of the code examples of this section are intended to be illustrative of technical details relevant to Maxima programming as their purpose, and consequently are intentionally elementary in character.

Learning any sort of programming language, including Maxima programming expressions, is a subjective process. In any case, it is essential to have enough technical know-how specific to the programming language in order to begin the learning process, even in cases where much positive transfer from other programming experience is involved.

Much can be accomplished mathematically using Maxima without having to resort to in-depth knowledge and proficiency in the technical details of Maxima programming expressions. However, Maxima programming expressions are frequently essential for the purpose of defining functions, both in the programming sense of the term, but also more relevantly, to the mathematical sense. For that reason alone, familiarity and sufficient proficiency with Maxima programming expressions should be given some attention.

One way to begin the learning process is to become familiar with enough of the programming essentials to accomplish independent efforts toward accomplishing some specific programming goal of interest.  The other way is to study the many available programming expressions of others. This section is intended to provide the essentials toward learning by whatever means is chosen.

The following table shows some built-in ingredients related to Maxima programming expressions:
{| class=&quot;wikitable&quot;
|+Maxima Programming Category
|if
|unless
|errcatch
|prederror
|-
|block
|for
|error
|return
|-
|catch
|from
|warning
|throw 
|-
|local
|thru
|errormsg
|sstatus
|-
|garbage_collect
|step
|errormsg
|status
|-
|do
|next
|go
|
|-
|while
|in
|
|
|}

Some of these programming expression ingredients can also be considered as belonging to one or more other categories than the Programming category.

=== Block Expressions ===
Arguably, the first expressions to consider in the context of Maxima programming are '''''block''''' expressions. Block expressions as programming ingredients come in two flavors:

* &lt;code&gt;( expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt; )&lt;/code&gt;
* &lt;code&gt;block ([v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;], expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;)&lt;/code&gt;

The first form of a block expression is equivalent to the second form, but without the first list argument: &lt;code&gt;[v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;]&lt;/code&gt;, as in &lt;code&gt;block (expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;, unless &lt;code&gt;return&lt;/code&gt; or &lt;code&gt;go&lt;/code&gt; are used in the block expression. In that, case the form &lt;code&gt;block (expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;)&lt;/code&gt; must be used.

The purpose of the list argument,  &lt;code&gt;[v&lt;sub&gt;1&lt;/sub&gt;,v&lt;sub&gt;2,&lt;/sub&gt;…,v&lt;sub&gt;m&lt;/sub&gt;]&lt;/code&gt; is to declare the values of identifiers of the list to be local to the &lt;code&gt;block&lt;/code&gt;. If there is no need for local identifiers, the list argument can be omitted, unless &lt;code&gt;return&lt;/code&gt; or &lt;code&gt;go&lt;/code&gt; are used in the &lt;code&gt;block&lt;/code&gt; expression, and either form is sufficient.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;/* This block expression */
(%i1)	(x : 2, x^2);
(%o1)	4

/* Is equivalent to this block expression */
(%i2)	block (x : 2, x^2);
(%o2)	4&lt;/syntaxhighlight&gt;So, in the case where values of identifiers local to the &lt;code&gt;block&lt;/code&gt; of expressions are not required, then the choice of either form of the &lt;code&gt;block&lt;/code&gt; expression is a matter of user preference, . In both cases, the values of identifiers referenced in the &lt;code&gt;block&lt;/code&gt; are global, and not local to the &lt;code&gt;block&lt;/code&gt;.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
/* The value 3 assigned to x is global */
(%i3)	x : 3;
(x)	    3

/* The value 2 assigned to x in the block is global */
(%i4)	(x : 2, x^2);
(%o4)	4

/* The global value assigned to x in the block is 2 not 3 */
(%i5)	x;
(%o5)	2
&lt;/syntaxhighlight&gt;Values of identifiers local to the &lt;code&gt;block&lt;/code&gt; may not be global:&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;/* the value of identifier y is local only */
(%i6)	block ([y], y : 4, y);
(%o6)	4

/* the global value of identifier y is not 4, but is itself */
(%i7)	y;
(%o7)	y

/* the values of identifiers x and y are both local */
(%i8)	block ([x,y], x : 3, y : 4, x);
(%o8)	3

/* the global value of identifier x is not 3, but is 2 */
(%i9)	x;
(%o9)	2

/* the global value of identifier y is not 4, but is itself */
(%i10)	y;
(%o10)	y&lt;/syntaxhighlight&gt;

Regardless of the form of the &lt;code&gt;block&lt;/code&gt; expressions these have in common the comma-separated expression arguments &lt;code&gt;expr&lt;sub&gt;1&lt;/sub&gt;, expr&lt;sub&gt;2&lt;/sub&gt;,…, expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;  which are evaluated each in turn from first to last (unless the evaluation sequence is modified by by the &lt;code&gt;go&lt;/code&gt;, &lt;code&gt;throw&lt;/code&gt;, or &lt;code&gt;return&lt;/code&gt; operators), and the value of the block expression is the value of  &lt;code&gt;expr&lt;sub&gt;n&lt;/sub&gt;&lt;/code&gt;. 

The main purpose of the &lt;code&gt;block&lt;/code&gt; expression, regardless of the form, it to group expressions that are related in some manner, and the value of the last expression may be the only value of interest. However, there are very few limitations imposed on the nature of the &lt;code&gt;block&lt;/code&gt; expression arguments, so it might be the case that the purpose of evaluating the &lt;code&gt;block&lt;/code&gt; expression has been achieved before the last expression argument is evaluated, in which case the value of the &lt;code&gt;block&lt;/code&gt; expression may not necessarily be the value of the last argument expression.

One way to accomplish that is to use an empty string as the last argument expression with the option flag &lt;code&gt;stringdisp&lt;/code&gt;set to &lt;code&gt;false&lt;/code&gt; which is the default value.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i11)	stringdisp;
(%o11)	false

(%i12)	block ([x,y], x : 3, y : 4, x, &quot;&quot;);
(%o12)	

(%i13)	block ([x,y], x : 3, y : 4, x)$
&lt;/syntaxhighlight&gt;
The display of the value of the &lt;code&gt;block&lt;/code&gt; expression may be suppressed using a &lt;code&gt;$&lt;/code&gt; to end the input expression instead of a semi-colon. Either technique produces a &lt;code&gt;block&lt;/code&gt; expression value, but the value is not displayed. If a &lt;code&gt;return&lt;/code&gt; operator is evaluated as a argument expression, this will cause evaluation of expression arguments to end explicitly, and the value of the &lt;code&gt;return&lt;/code&gt; operator becomes the value of the &lt;code&gt;block&lt;/code&gt; expression.&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i14)	is (equal (x,2));
(%o14)	true

%i15)	block (if is (equal (x,2)) then return (x), &quot; x not 2&quot;);
(%o15)	2

(%i16)	x : 3;
(x)	3

(%i17)	block (if is (equal (x,2)) then return (x), &quot;x not 2&quot;);
(%o17)	x not 2
&lt;/syntaxhighlight&gt;One way to modify the first-to-last evaluation sequence of a bock expression is by way of a go operator with a label argument ( &quot;a go to loop&quot;) as the following exemplifies:&lt;syntaxhighlight lang=&quot;maxima&quot;&gt;
(%i18)	sum_to_n (n) := block ( [i : 1, total : 0],
	                             loop,
	                                total : total + i,
	                                i : i + 1,
	                                if i &lt;= n then go (loop),
	                             total)$

(%i19)	sum_to_n(25);
(%o19)	325

(%i20)	n;
(%o20)	n

(%i21)	i;
(%o21)	i

(%i22)	total;
(%o22)	total
&lt;/syntaxhighlight&gt;Note the following:

* &lt;code&gt;block ([ i : 1,total : 0], ...)&lt;/code&gt;: The list argument creates a local environment with local identifiers &lt;code&gt;i&lt;/code&gt; and &lt;code&gt;total&lt;/code&gt;. The function argument &lt;code&gt;n&lt;/code&gt; is also a local identifier
* &lt;code&gt;loop&lt;/code&gt;: This label serves as a target inside the &lt;code&gt;block&lt;/code&gt; expression to where &lt;code&gt;go (loop)&lt;/code&gt; can jump.
* &lt;code&gt;if i &lt;= n then go (loop)&lt;/code&gt;: This conditional expression causes the go (loop) operator to be evaluated if the condition is &lt;code&gt;true&lt;/code&gt;.
* &lt;code&gt;total&lt;/code&gt;: This local identifier is the returned value of the block.
It should also be worth noting that the identifiers &lt;code&gt;n&lt;/code&gt;, &lt;code&gt;i&lt;/code&gt;, and &lt;code&gt;total&lt;/code&gt; have local values assigned within the block, but their global values are themselves. Also notice that the identifiers &lt;code&gt;i&lt;/code&gt; and &lt;code&gt;total&lt;/code&gt; were both declared local and assigned initial values within the &lt;code&gt;block&lt;/code&gt; list argument..

=== Functions ===

=== Lisp and Maxima ===

{{BookCat}}</text>
      <sha1>2iu2j4ezxxzyvu0kt7z2hf2fr32qysc</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:Amstshakila</title>
    <ns>3</ns>
    <id>485516</id>
    <revision>
      <id>4669857</id>
      <parentid>4669179</parentid>
      <timestamp>2026-09-13T08:33:51Z</timestamp>
      <contributor>
        <username>SHB2000</username>
        <id>3332924</id>
      </contributor>
      <comment>/* I have added a tag to a page you created */ Reply</comment>
      <origin>4669857</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="993" sha1="cniwy9ld69kvgzqyica0j22iioxeiry" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:User:Amstshakila]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[User talk:Amstshakila|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 10:53, 7 September 2026 (UTC)

:Deleted. --[[User:SHB2000|SHB2000]] ([[User talk:SHB2000|discuss]] • [[Special:Contributions/SHB2000|contribs]]) 08:33, 13 September 2026 (UTC)</text>
      <sha1>cniwy9ld69kvgzqyica0j22iioxeiry</sha1>
    </revision>
  </page>
  <page>
    <title>A-level Computing AQA Paper 1 Skeleton program 2027</title>
    <ns>0</ns>
    <id>485519</id>
    <revision>
      <id>4669781</id>
      <parentid>4669632</parentid>
      <timestamp>2026-09-12T20:12:07Z</timestamp>
      <contributor>
        <username>Omphalographer</username>
        <id>3427146</id>
      </contributor>
      <comment>delete - ?</comment>
      <origin>4669781</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="350" sha1="a0mvgjoxrhu9chp6gnass714yu59inq" xml:space="preserve">{{delete|This does not appear to be a book.}}

This is for the 2027 AQA A-level Computer Science Specification (7517).

This is where suggestions can be made about what some of the questions might be and how we can solve them.

'''Please be respectful and do not vandalise the page, as this may affect students' preparation for exams!'''

{{shelves}}</text>
      <sha1>a0mvgjoxrhu9chp6gnass714yu59inq</sha1>
    </revision>
  </page>
  <page>
    <title>User:Salwahmagala</title>
    <ns>2</ns>
    <id>485566</id>
    <revision>
      <id>4669751</id>
      <timestamp>2026-09-12T12:09:23Z</timestamp>
      <contributor>
        <username>Salwahmagala</username>
        <id>3620024</id>
      </contributor>
      <comment>added bullets</comment>
      <origin>4669751</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="21828" sha1="bzw3kvijrnfg5a7skyomnnoh83vv6uw" xml:space="preserve">*
* Digital Citizenship: Learning to Be Safe, Smart and Responsible Online
* A Wikibook for Grade 9 Learners
*  ----
* Table of Contents

# Introduction
# What Is Digital Citizenship?
# Understanding the Digital World
# Staying Safe Online
# Privacy and Personal Information
# Social Media and Responsible Use
# Digital Footprints and Online Reputation
# Cyberbullying and Online Respect
# Fake News, Misinformation and Reliable Information
# Digital Wellbeing and Healthy Technology Use
# Copyright and Respecting Other People's Work
# Communicating Responsibly Online
# Becoming a Responsible Digital Citizen
# Glossary

----

= Introduction =
Technology has become an important part of everyday life. People use smartphones, computers and the internet to communicate, study, find information, create content, work and entertain themselves.

For young people, digital technology can provide many opportunities for learning and creativity. At the same time, the digital world can expose young people to risks such as cyberbullying, misinformation, privacy problems, scams and harmful content.

UNICEF explains that digital technology can provide important opportunities for children while also creating risks that need to be managed. It therefore emphasizes the importance of teaching children digital-literacy and online-safety skills.

Digital citizenship is about learning how to participate in the digital world in a safe, responsible, respectful and informed way.

This book has been designed for Grade 9 learners. It introduces important digital-citizenship concepts through explanations, examples, activities and review questions.

The goal of this book is simple:&lt;blockquote&gt;'''Be safe. Be smart. Be respectful. Be responsible.'''&lt;/blockquote&gt;

= Chapter 1: What Is Digital Citizenship? =

== Learning Objectives ==
By the end of this chapter, learners should be able to:

* Define digital citizenship.
* Explain why digital citizenship is important.
* Identify characteristics of a responsible digital citizen.
* Explain how online actions can affect other people.

== 1.1 What Is Digital Citizenship? ==
Digital citizenship refers to the responsible, safe, respectful and informed use of digital technologies.

A digital citizen is a person who uses digital devices and online platforms while considering their own safety, the rights of others and the possible effects of their actions.

Digital citizenship is not only about knowing how to operate a computer or smartphone. It is also about making good decisions when using technology.

For example, a responsible digital citizen:

* Protects personal information.
* Uses respectful language online.
* Checks information before sharing it.
* Respects other people's work.
* Reports harmful behaviour.
* Thinks about the consequences of online actions.

== 1.2 Why Is Digital Citizenship Important? ==
Young people spend an increasing amount of time using digital technologies for learning, communication and entertainment.

UNICEF notes that digital connectivity can help children learn, communicate and develop skills, but it can also expose them to risks.

Learning digital citizenship therefore helps learners make informed choices.

=== Example ===
Imagine that Amina receives a message claiming that her school is closed the following day.

Instead of immediately forwarding it to her classmates, she checks the school's official communication channels.

This is an example of responsible digital citizenship.

== Activity ==
In groups, list five things a responsible digital citizen should do.

== Think About It ==
What could happen if people used the internet without considering how their actions affect others?

== Review Questions ==

# What is digital citizenship?
# Give three examples of responsible digital behaviour.
# Why is digital citizenship important?
# How can online actions affect other people?

----

= Chapter 2: Understanding the Digital World =

== Learning Objectives ==
By the end of this chapter, learners should be able to:

* Identify common digital technologies.
* Explain different uses of the internet.
* Distinguish between different types of online platforms.
* Explain some benefits of digital technology.

== 2.1 What Is Digital Technology? ==
Digital technology includes electronic tools and systems that allow people to create, store, process and communicate information.

Examples include:

* Smartphones
* Computers
* Tablets
* Digital cameras
* Smart televisions
* Online learning platforms
* Social media platforms

== 2.2 The Internet ==
The internet is a worldwide network that connects computers and other digital devices.

People use the internet to:

* Search for information.
* Communicate.
* Learn.
* Shop.
* Work.
* Share information.
* Watch videos.
* Listen to music.
* Participate in online communities.

== 2.3 Social Media ==
Social media refers to online platforms that allow users to create, share and interact with content.

Examples include platforms used for:

* Messaging
* Video sharing
* Photo sharing
* Discussions
* Professional networking

Social media can be useful for education, communication and creativity, but users should also understand its risks.

== Activity ==
Write down five digital technologies you use or see around you.

For each one, write one educational use.

== Review Questions ==

# What is digital technology?
# Give four examples of digital technologies.
# What are three ways people use the internet?
# What is social media?

----

= Chapter 3: Staying Safe Online =

== Learning Objectives ==
Learners should be able to:

* Identify common online risks.
* Explain how to create stronger passwords.
* Recognize suspicious messages.
* Explain why personal information should be protected.

== 3.1 What Is Online Safety? ==
Online safety means taking steps to protect yourself, your information and your accounts while using the internet.

UNICEF identifies online safety and data protection as important areas of child protection in digital environments.

== 3.2 Strong Passwords ==
A password helps protect an account from unauthorized access.

A good password should be difficult for other people to guess.

Avoid using:

* Your name
* Your birthday
* Your school name
* Your telephone number
* Simple sequences such as 123456

Where possible, use a strong and unique password for each important account.

== 3.3 Suspicious Messages ==
Some online messages attempt to trick users into revealing information or clicking dangerous links.

=== Example ===
&lt;blockquote&gt;&quot;Congratulations! You have won a new phone. Click this link and enter your password to claim your prize.&quot;&lt;/blockquote&gt;A careful user should not immediately click the link or provide a password.

Instead, the user should verify whether the message is genuine.

== 3.4 Other Online Risks ==
Learners may encounter:

* Scams
* Phishing
* Malware
* Fake accounts
* Identity theft
* Cyberbullying
* Harmful content

== Activity: Safety Detective ==
Read this message:&lt;blockquote&gt;&quot;Your account will be deleted today. Send us your password immediately.&quot;&lt;/blockquote&gt;Answer:

# Does this message appear trustworthy?
# What warning signs do you see?
# What should the user do?

== Review Questions ==

# What does online safety mean?
# Why should passwords be protected?
# What is phishing?
# Give three examples of online risks.

----

= Chapter 4: Privacy and Personal Information =

== Learning Objectives ==
Learners should be able to:

* Define personal information.
* Identify information that should be protected.
* Explain why privacy is important.
* Identify unsafe sharing practices.

== 4.1 What Is Personal Information? ==
Personal information is information that can identify or provide details about a person.

Examples may include:

* Full name
* Home address
* Telephone number
* Password
* School information
* Personal photographs
* Location
* Account details

Not all information should be shared publicly.

== 4.2 Why Does Privacy Matter? ==
Information shared online can sometimes be copied, stored or redistributed.

UNICEF highlights data protection and children's privacy as important concerns in digital environments.

=== Example ===
John receives a message from someone he does not know asking for his home address.

John should not provide it simply because the person asks.

He should consider:&lt;blockquote&gt;&quot;Why does this person need my information?&quot;&lt;/blockquote&gt;

== Activity ==
Place each item into one of two groups:

'''Safe to share publicly'''

'''Should be kept private'''

Items:

* Favourite colour
* Home address
* Password
* Favourite school subject
* Telephone number
* Personal photograph
* School location

Discuss your answers.

== Review Questions ==

# What is personal information?
# Give four examples.
# Why should passwords be kept private?
# Why should you be careful when sharing photographs online?

----

= Chapter 5: Social Media and Responsible Use =

== Learning Objectives ==
Learners should be able to:

* Explain what social media is.
* Identify benefits of social media.
* Identify possible risks.
* Explain responsible social-media behaviour.

== 5.1 Benefits of Social Media ==
Social media can help people:

* Communicate with friends and family.
* Share ideas.
* Learn new things.
* Promote businesses.
* Participate in communities.
* Discover educational resources.

== 5.2 Risks of Social Media ==
However, social media may also expose users to:

* Cyberbullying
* Misinformation
* Privacy risks
* Scams
* Harmful content
* Excessive screen use

UNICEF notes that children can encounter cyberbullying, harmful content and other risks online.

== 5.3 Responsible Social-Media Use ==
A responsible user should:

* Think before posting.
* Avoid sharing private information.
* Respect other people.
* Check information before sharing.
* Report harmful behaviour.
* Use privacy settings appropriately.

== Activity ==
Imagine your friend posts an embarrassing photograph of another learner without permission.

Discuss:

# Is this responsible?
# Why or why not?
# What could the friend do instead?

== Review Questions ==

# What is social media?
# Give three benefits.
# Give three risks.
# What does &quot;think before you post&quot; mean?

----

= Chapter 6: Digital Footprints and Online Reputation =

== Learning Objectives ==
Learners should be able to:

* Define a digital footprint.
* Explain how digital footprints are created.
* Explain why online reputation matters.
* Identify ways of creating a positive digital footprint.

== 6.1 What Is a Digital Footprint? ==
A digital footprint is the record or trail of information created by a person's activities online.

For example, a person's digital footprint may include:

* Posts
* Comments
* Photos
* Videos
* Likes
* Public profiles
* Reviews

== 6.2 Think Before You Post ==
Before posting something online, ask:&lt;blockquote&gt;Would I be comfortable if my teacher, parent or future employer saw this?&lt;/blockquote&gt;If the answer is no, think carefully before posting.

== 6.3 Building a Positive Digital Footprint ==
A positive digital footprint can include:

* Educational projects
* Creative work
* Positive contributions
* Helpful discussions
* Respectful communication

== Activity ==
Write three things you would like your future digital footprint to say about you.

== Review Questions ==

# What is a digital footprint?
# Give three examples.
# Why is your online reputation important?
# How can you create a positive digital footprint?

----

= Chapter 7: Cyberbullying and Online Respect =

== Learning Objectives ==
Learners should be able to:

* Define cyberbullying.
* Identify examples.
* Explain how cyberbullying can affect people.
* Identify appropriate responses.

== 7.1 What Is Cyberbullying? ==
Cyberbullying is bullying or harassment carried out using digital technologies.

It can occur through:

* Messages
* Social media
* Online games
* Group chats
* Websites
* Comment sections

== 7.2 Examples ==
Examples include:

* Sending repeated insulting messages.
* Spreading embarrassing rumours.
* Sharing someone's photograph to humiliate them.
* Creating an account to impersonate someone.
* Encouraging others to exclude someone from an online group.

== 7.3 What Should You Do? ==
If someone experiences cyberbullying, they can:

# Avoid responding aggressively.
# Save evidence where appropriate.
# Block or mute the person.
# Report the behaviour.
# Tell a trusted adult, teacher or appropriate authority.
# Seek support.

UNICEF identifies cyberbullying and peer-to-peer violence as risks that can affect young people online.

== Activity ==

=== Scenario ===
Sarah discovers that classmates have created a group chat where they are insulting another learner.

What should Sarah do?

Discuss possible responsible actions.

== Review Questions ==

# What is cyberbullying?
# Give two examples.
# What should a learner do after experiencing cyberbullying?
# Why is online respect important?

----

= Chapter 8: Fake News, Misinformation and Reliable Information =

== Learning Objectives ==
Learners should be able to:

* Explain misinformation.
* Identify warning signs of unreliable information.
* Check information before sharing it.
* Identify reliable sources.

== 8.1 What Is Misinformation? ==
Misinformation is false or inaccurate information that is shared without necessarily intending to cause harm.

Some false information is deliberately created or spread to deceive people.

== 8.2 Why Is This Important? ==
False information can influence people's decisions and beliefs.

UNESCO identifies misinformation and disinformation as important areas of Media and Information Literacy education.

== 8.3 How to Check Information ==
Before sharing information, ask:

=== 1. Who published it? ===
Is the source identifiable?

=== 2. When was it published? ===
Could the information be outdated?

=== 3. What evidence is provided? ===
Are there reliable sources?

=== 4. Can another trustworthy source confirm it? ===
Compare the information with other reputable sources.

=== 5. Does the headline seem designed only to make you angry or afraid? ===
Emotional headlines require careful checking.

== Activity: Fact Checker ==
Your friend sends you a message saying:&lt;blockquote&gt;&quot;All schools in Uganda will close tomorrow.&quot;&lt;/blockquote&gt;Before sharing it, list three things you would do to check whether it is true.

== Review Questions ==

# What is misinformation?
# Why should information be checked before sharing?
# Name three questions you can ask about a source.
# Why should learners compare information from different reliable sources?

----

= Chapter 9: Digital Wellbeing and Healthy Technology Use =

== Learning Objectives ==
Learners should be able to:

* Explain digital wellbeing.
* Recognize unhealthy technology habits.
* Identify ways to balance online and offline activities.

== 9.1 What Is Digital Wellbeing? ==
Digital wellbeing refers to maintaining a healthy and balanced relationship with technology.

Technology can support learning and communication, but excessive or unhealthy use can interfere with other areas of life.

UNICEF's research on childhood in a digital world discusses digital skills, screen time and children's wellbeing.

== 9.2 Signs of an Unhealthy Digital Routine ==
A learner may need to reconsider their technology habits if they:

* Regularly lose sleep because of devices.
* Ignore schoolwork because of entertainment.
* Spend most free time online.
* Find it difficult to stop using a device.
* Avoid important offline activities.

== 9.3 Creating Balance ==
Healthy habits may include:

* Taking regular breaks.
* Prioritizing schoolwork.
* Getting enough sleep.
* Spending time with family and friends.
* Participating in physical activities.
* Setting appropriate technology boundaries.

== Activity ==
Create a one-day timetable showing how you will balance:

* Schoolwork
* Technology
* Sleep
* Family time
* Exercise
* Rest

== Review Questions ==

# What is digital wellbeing?
# Give three signs of an unhealthy digital routine.
# Why is balance important?
# Give three healthy technology habits.

----

= Chapter 10: Copyright and Respecting Other People's Work =

== Learning Objectives ==
Learners should be able to:

* Explain copyright.
* Understand why creators should receive credit.
* Distinguish between copying and using information responsibly.
* Explain plagiarism.

== 10.1 What Is Copyright? ==
Copyright is a form of legal protection given to creators of original works.

Creative works may include:

* Books
* Articles
* Photographs
* Music
* Videos
* Artwork
* Computer programs

== 10.2 Giving Credit ==
When using someone else's work, learners should follow the applicable permission and licensing rules and give appropriate credit where required.

For example, when using information from a website in a school assignment, the learner should identify the source.

== 10.3 Plagiarism ==
Plagiarism is presenting another person's work or ideas as your own without appropriate acknowledgment.

=== Example ===
If Maria copies three paragraphs from a website and submits them as her own work without citation, she may be committing plagiarism.

== Activity ==
Rewrite this sentence in your own words:&lt;blockquote&gt;&quot;The internet provides access to a huge amount of information.&quot;&lt;/blockquote&gt;Then discuss why rewriting alone does not remove the need to acknowledge the source when the idea came from another person's work.

== Review Questions ==

# What is copyright?
# Why should creators be respected?
# What is plagiarism?
# Why should sources be acknowledged?

----

= Chapter 11: Communicating Responsibly Online =

== Learning Objectives ==
Learners should be able to:

* Explain responsible online communication.
* Identify respectful and disrespectful communication.
* Understand the importance of tone.
* Apply good digital etiquette.

== 11.1 What Is Online Communication? ==
Online communication includes communicating through:

* Email
* Messaging applications
* Social media
* Discussion forums
* Online classrooms
* Video calls

== 11.2 Think Before You Send ==
A message may be interpreted differently from how the sender intended it.

Before sending a message, ask:

* Is it true?
* Is it necessary?
* Is it respectful?
* Could it hurt someone?
* Would I say the same thing face-to-face?

== 11.3 Digital Etiquette ==
Digital etiquette means following appropriate rules of behaviour when communicating online.

Good digital etiquette includes:

* Using respectful language.
* Avoiding unnecessary arguments.
* Listening to different opinions.
* Avoiding insults.
* Not sharing private conversations without permission.
* Giving people time to respond.

== Activity ==
Rewrite this message to make it respectful:&lt;blockquote&gt;&quot;You are completely wrong! You don't know anything.&quot;&lt;/blockquote&gt;Possible improved version:&lt;blockquote&gt;&quot;I understand your point, but I have a different opinion. Here is why...&quot;&lt;/blockquote&gt;

== Review Questions ==

# What is online communication?
# What is digital etiquette?
# Why can tone be difficult to understand online?
# Give three examples of respectful online communication.

----

= Chapter 12: Becoming a Responsible Digital Citizen =

== Learning Objectives ==
By the end of this chapter, learners should be able to:

* Apply the principles learned throughout the book.
* Explain the responsibilities of digital citizens.
* Develop personal rules for responsible technology use.

== 12.1 The Responsible Digital Citizen ==
A responsible digital citizen:

=== Thinks critically ===
They do not automatically believe everything they see online.

=== Protects privacy ===
They are careful about personal information.

=== Communicates respectfully ===
They understand that there are real people behind online accounts.

=== Protects themselves ===
They recognize scams, suspicious messages and unsafe situations.

=== Respects others ===
They do not bully, harass or deliberately embarrass other people.

=== Respects intellectual property ===
They acknowledge other people's creative work.

=== Maintains balance ===
They use technology without allowing it to control their lives.

== 12.2 The Digital Citizenship Checklist ==
Before posting, sharing or sending something, ask:

'''STOP. THINK. CHECK.'''

=== STOP ===
Do not react immediately.

=== THINK ===
Consider the possible consequences.

=== CHECK ===
Verify the information and consider whether the action is safe and respectful.

== Final Activity: My Digital Citizenship Pledge ==
Complete the following:&lt;blockquote&gt;'''I promise to be a responsible digital citizen by...'''&lt;/blockquote&gt;

#  ----
#  ----
#  ----
#  ----
#  ----

Share your pledge with the class.
----

= Glossary =

=== Digital Citizen ===
A person who uses digital technology safely, responsibly and respectfully.

=== Digital Citizenship ===
Responsible and informed participation in the digital world.

=== Digital Footprint ===
The record or trail of information created by a person's online activities.

=== Cyberbullying ===
Bullying or harassment carried out through digital technologies.

=== Misinformation ===
False or inaccurate information that is shared, regardless of whether there was an intention to deceive.

=== Phishing ===
A technique used to trick people into revealing sensitive information, often through deceptive messages or websites.

=== Privacy ===
The ability to control information about yourself and how it is shared.

=== Copyright ===
Legal protection for original creative works.

=== Plagiarism ===
Presenting another person's work or ideas as one's own without appropriate acknowledgment.

=== Digital Wellbeing ===
Maintaining a healthy and balanced relationship with digital technology.

=== Social Media ===
Digital platforms that allow people to create, share and interact with content.

#</text>
      <sha1>bzw3kvijrnfg5a7skyomnnoh83vv6uw</sha1>
    </revision>
  </page>
  <page>
    <title>AI For Beginners</title>
    <ns>0</ns>
    <id>485567</id>
    <redirect title="User:AI For Beginners" />
    <revision>
      <id>4669759</id>
      <timestamp>2026-09-12T13:39:14Z</timestamp>
      <contributor>
        <username>Sisterian</username>
        <id>3123918</id>
      </contributor>
      <comment>Sisterian moved page [[AI For Beginners]] to [[User:AI For Beginners]]</comment>
      <origin>4669759</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="35" sha1="sphcnrlkehpbwjhcz5rpfoblngv38fo" xml:space="preserve">#REDIRECT [[User:AI For Beginners]]</text>
      <sha1>sphcnrlkehpbwjhcz5rpfoblngv38fo</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:Harshvardhanrai0905</title>
    <ns>3</ns>
    <id>485568</id>
    <redirect title="User talk:Heathcliff00" />
    <revision>
      <id>4669769</id>
      <timestamp>2026-09-12T16:33:00Z</timestamp>
      <contributor>
        <username>QueerEcofeminist</username>
        <id>474408</id>
      </contributor>
      <comment>QueerEcofeminist moved page [[User talk:Harshvardhanrai0905]] to [[User talk:Heathcliff00]]: Automatically moved page while renaming the user &quot;[[Special:CentralAuth/Harshvardhanrai0905|Harshvardhanrai0905]]&quot; to &quot;[[Special:CentralAuth/Heathcliff00|Heathcliff00]]&quot;</comment>
      <origin>4669769</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="36" sha1="6p3e4k0z5owfqc7derfg1f7ddb35klq" xml:space="preserve">#REDIRECT [[User talk:Heathcliff00]]</text>
      <sha1>6p3e4k0z5owfqc7derfg1f7ddb35klq</sha1>
    </revision>
  </page>
  <page>
    <title>Talk:SPARQL/UNION</title>
    <ns>1</ns>
    <id>485569</id>
    <revision>
      <id>4669776</id>
      <timestamp>2026-09-12T17:35:12Z</timestamp>
      <contributor>
        <username>Fl.schmitt</username>
        <id>184773</id>
      </contributor>
      <comment>/* &quot;Big City&quot; Examples broken */ new section</comment>
      <origin>4669776</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="590" sha1="sum4n91y6nvd5jm4dhtxgfmna3x95jb" xml:space="preserve">== &quot;Big City&quot; Examples broken ==
Sadly, since {{Q|1637706}} was removed from almost all cities in 2024, the first UNION example doesn't work any more. Additionally, in the second part (big cities in the European Union), the result for the &lt;code&gt;?city&lt;/code&gt; variable isn't restricted to {{Q|515}} entities but applies also for territorial subdivisions (e.g. states in Germany). I'm searching for a similar query that doesn't hit the timeout... [[User:Fl.schmitt|Fl.schmitt]] ([[User talk:Fl.schmitt|discuss]] • [[Special:Contributions/Fl.schmitt|contribs]]) 17:35, 12 September 2026 (UTC)</text>
      <sha1>sum4n91y6nvd5jm4dhtxgfmna3x95jb</sha1>
    </revision>
  </page>
  <page>
    <title>Baiyi Zhuan</title>
    <ns>0</ns>
    <id>485570</id>
    <revision>
      <id>4669793</id>
      <timestamp>2026-09-13T02:26:11Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>Created page with &quot;__NOTOC__ {{incomplete translation}} {{Translation header  | title    = Baiyi Zhuan (百夷傳)  | author   = Qian Guxun (錢古訓)  | override_editor   = Palace Museum Library  | translator = Maruti Mishra  | section  =  | previous =  | next     =  | shortcut =   | year     =   | language = zh  | original =   | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty...&quot;</comment>
      <origin>4669793</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="18388" sha1="hr7isgegy0uj2xeddkla9jm2sszm3x2" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|
|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}
===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>hr7isgegy0uj2xeddkla9jm2sszm3x2</sha1>
    </revision>
    <revision>
      <id>4669794</id>
      <parentid>4669793</parentid>
      <timestamp>2026-09-13T02:35:49Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669794</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="18754" sha1="pfbpuyv0vf2zjdpsozlk5c7v6euh7m9" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|
|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}
===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>pfbpuyv0vf2zjdpsozlk5c7v6euh7m9</sha1>
    </revision>
    <revision>
      <id>4669796</id>
      <parentid>4669794</parentid>
      <timestamp>2026-09-13T02:46:29Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669796</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="19245" sha1="g1l3ypl6vzbizbtoq3asv87jzfatkrn" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|
|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>g1l3ypl6vzbizbtoq3asv87jzfatkrn</sha1>
    </revision>
    <revision>
      <id>4669797</id>
      <parentid>4669796</parentid>
      <timestamp>2026-09-13T02:47:39Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <minor />
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669797</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="19317" sha1="hi959ef99gwdtherlsse0bnwtf1khq6" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|
|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>hi959ef99gwdtherlsse0bnwtf1khq6</sha1>
    </revision>
    <revision>
      <id>4669799</id>
      <parentid>4669797</parentid>
      <timestamp>2026-09-13T03:11:20Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669799</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="20540" sha1="nkpvxbtbrr2rj98geflwgqdep2kvfbh" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>nkpvxbtbrr2rj98geflwgqdep2kvfbh</sha1>
    </revision>
    <revision>
      <id>4669800</id>
      <parentid>4669799</parentid>
      <timestamp>2026-09-13T03:19:42Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669800</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="20896" sha1="1fuw0qwluvq9hadtxd2zbtk647es67b" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>1fuw0qwluvq9hadtxd2zbtk647es67b</sha1>
    </revision>
    <revision>
      <id>4669802</id>
      <parentid>4669800</parentid>
      <timestamp>2026-09-13T03:30:33Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669802</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="21610" sha1="buycqrzsbxhptmxpws19u6blyuf3xj0" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>buycqrzsbxhptmxpws19u6blyuf3xj0</sha1>
    </revision>
    <revision>
      <id>4669803</id>
      <parentid>4669802</parentid>
      <timestamp>2026-09-13T04:07:14Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669803</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="23163" sha1="9stuznv03kgwf557dx7nmr865vgmjzo" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|
|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>9stuznv03kgwf557dx7nmr865vgmjzo</sha1>
    </revision>
    <revision>
      <id>4669807</id>
      <parentid>4669803</parentid>
      <timestamp>2026-09-13T04:16:17Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669807</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="23721" sha1="t8oo2sdngkgprd71u6n8kpvrlmgpp6h" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>t8oo2sdngkgprd71u6n8kpvrlmgpp6h</sha1>
    </revision>
    <revision>
      <id>4669808</id>
      <parentid>4669807</parentid>
      <timestamp>2026-09-13T04:27:59Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669808</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="24591" sha1="eavd10ua8d7ppij0edvaj9qabtp6o19" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>eavd10ua8d7ppij0edvaj9qabtp6o19</sha1>
    </revision>
    <revision>
      <id>4669809</id>
      <parentid>4669808</parentid>
      <timestamp>2026-09-13T04:33:31Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669809</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="24861" sha1="r8p2br44yhqd3hn3msl80qkgh50uzdi" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>r8p2br44yhqd3hn3msl80qkgh50uzdi</sha1>
    </revision>
    <revision>
      <id>4669810</id>
      <parentid>4669809</parentid>
      <timestamp>2026-09-13T05:24:15Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669810</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="25668" sha1="4fne6shejzas9mwrvkj4cu22q4pzod3" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>4fne6shejzas9mwrvkj4cu22q4pzod3</sha1>
    </revision>
    <revision>
      <id>4669811</id>
      <parentid>4669810</parentid>
      <timestamp>2026-09-13T05:30:49Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669811</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="25985" sha1="r4rd1tmpcdhhg74k2bmwk67tlkm2ger" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>r4rd1tmpcdhhg74k2bmwk67tlkm2ger</sha1>
    </revision>
    <revision>
      <id>4669812</id>
      <parentid>4669811</parentid>
      <timestamp>2026-09-13T05:38:14Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669812</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="26279" sha1="gbk86umljxzooh1d6apdlxlxj0uckr3" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>gbk86umljxzooh1d6apdlxlxj0uckr3</sha1>
    </revision>
    <revision>
      <id>4669813</id>
      <parentid>4669812</parentid>
      <timestamp>2026-09-13T05:54:57Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669813</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="27028" sha1="8raf46ozbzdn6685vkqsi8azw3rq6g4" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = Palace Museum Library
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>8raf46ozbzdn6685vkqsi8azw3rq6g4</sha1>
    </revision>
    <revision>
      <id>4669814</id>
      <parentid>4669813</parentid>
      <timestamp>2026-09-13T05:55:52Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <minor />
      <origin>4669814</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="27007" sha1="7tdexa05v3x3nu8oro35qyf44za0rwv" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = Maruti Mishra
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>7tdexa05v3x3nu8oro35qyf44za0rwv</sha1>
    </revision>
    <revision>
      <id>4669815</id>
      <parentid>4669814</parentid>
      <timestamp>2026-09-13T05:56:31Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <minor />
      <origin>4669815</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="27005" sha1="dd9vuw5tlkihbidrhlknzuq0a9d1fij" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>dd9vuw5tlkihbidrhlknzuq0a9d1fij</sha1>
    </revision>
    <revision>
      <id>4669824</id>
      <parentid>4669815</parentid>
      <timestamp>2026-09-13T06:30:00Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669824</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="27156" sha1="g733kciygbwkdjp7zakdovkutsvt17a" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|
|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>g733kciygbwkdjp7zakdovkutsvt17a</sha1>
    </revision>
    <revision>
      <id>4669835</id>
      <parentid>4669824</parentid>
      <timestamp>2026-09-13T06:49:48Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669835</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="28152" sha1="19mdwwde0cc7tmxbqprcdzccm52uqbx" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>19mdwwde0cc7tmxbqprcdzccm52uqbx</sha1>
    </revision>
    <revision>
      <id>4669836</id>
      <parentid>4669835</parentid>
      <timestamp>2026-09-13T07:01:15Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Ethnic Groups and customs */</comment>
      <origin>4669836</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="28657" sha1="qyiqasw6tpyzpjkep2itbcagtgor5oj" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>qyiqasw6tpyzpjkep2itbcagtgor5oj</sha1>
    </revision>
    <revision>
      <id>4669843</id>
      <parentid>4669836</parentid>
      <timestamp>2026-09-13T07:22:46Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669843</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="29287" sha1="79o8od0yy2ockvfwa3fk6e8llbtpr4b" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the Eight Hundred '''Xífù''' ('''媳婦'''). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>79o8od0yy2ockvfwa3fk6e8llbtpr4b</sha1>
    </revision>
    <revision>
      <id>4669844</id>
      <parentid>4669843</parentid>
      <timestamp>2026-09-13T07:32:15Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669844</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="29790" sha1="fb7holf9s0teujra9l5qz7vgcok37gx" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些'''), '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>fb7holf9s0teujra9l5qz7vgcok37gx</sha1>
    </revision>
    <revision>
      <id>4669846</id>
      <parentid>4669844</parentid>
      <timestamp>2026-09-13T07:34:04Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <minor />
      <origin>4669846</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="30108" sha1="0ptapmkjz36wzubl2v3ucm7qfetqbhr" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|
|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>0ptapmkjz36wzubl2v3ucm7qfetqbhr</sha1>
    </revision>
    <revision>
      <id>4669847</id>
      <parentid>4669846</parentid>
      <timestamp>2026-09-13T07:44:06Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669847</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="30736" sha1="32bf0tirye9bnrsfqtbvnc0y93qc906" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>32bf0tirye9bnrsfqtbvnc0y93qc906</sha1>
    </revision>
    <revision>
      <id>4669852</id>
      <parentid>4669847</parentid>
      <timestamp>2026-09-13T08:02:04Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Translation */</comment>
      <origin>4669852</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="31382" sha1="3k8supmthq7yqsx8tx9lmxj5nil0izy" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|In Emperor Xianzong's 3rd year in the Yuan Dynasty, Emperor Shìzǔ (世祖; Kublai Khan) entered '''Lìjiāng''' ('''麗江''') from Tibet and himself in '''Yèyú''' ('''葉榆'''; Present Day Dali) brought peace to Yunnan. The following year, [he] commanded General UriyangKhadai to pacify the barbarian lands. The region was transformed into twenty circuits, four prefectures, forty-four districts and twenty-six departments, each with indigenous officials overseen by the Gold Teeth Commander in Chief&lt;ref&gt;A Tai Shan Leader likely.&lt;/ref&gt;. Officials were appointed to administer certain lands, returning by spring to avoid malarial miasma.


|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>3k8supmthq7yqsx8tx9lmxj5nil0izy</sha1>
    </revision>
    <revision>
      <id>4669853</id>
      <parentid>4669852</parentid>
      <timestamp>2026-09-13T08:02:26Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Translation */</comment>
      <origin>4669853</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="31382" sha1="kepbp59u78l0qfi30yfvjgpf1m90z80" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translator's note==


==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|In Emperor Xianzong's 3rd year in the Yuan Dynasty, Emperor Shìzǔ (世祖; Kublai Khan) entered '''Lìjiāng''' ('''麗江''') from Tibet and himself in '''Yèyú''' ('''葉榆'''; Present Day Dali) brought peace to Yunnan. The following year, [he] commanded General UriyangKhadai to pacify the barbarian lands. The region was transformed into twenty circuits, four prefectures, forty-four districts and twenty-six departments, each with indigenous officials overseen by the Gold Teeth Commander in Chief.&lt;ref&gt;A Tai Shan Leader likely.&lt;/ref&gt; Officials were appointed to administer certain lands, returning by spring to avoid malarial miasma.


|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>kepbp59u78l0qfi30yfvjgpf1m90z80</sha1>
    </revision>
    <revision>
      <id>4669860</id>
      <parentid>4669853</parentid>
      <timestamp>2026-09-13T08:54:50Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669860</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="32621" sha1="521ho3mbscwkusyrtbvzn72sbednxad" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|In Emperor Xianzong's 3rd year in the Yuan Dynasty, Emperor Shìzǔ (世祖; Kublai Khan) entered '''Lìjiāng''' ('''麗江''') from Tibet and himself in '''Yèyú''' ('''葉榆'''; Present Day Dali) brought peace to Yunnan. The following year, [he] commanded General UriyangKhadai to pacify the barbarian lands. The region was transformed into twenty circuits, four prefectures, forty-four districts and twenty-six departments, each with indigenous officials overseen by the Gold Teeth Commander in Chief.&lt;ref&gt;A Tai Shan Leader likely.&lt;/ref&gt; Officials were appointed to administer certain lands, returning by spring to avoid malarial miasma.
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|In the the 8th year of the Zhizheng era ('''1348 AD''')  Lùchuān (麓川) indigenous chief '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) had been countlessly harassing and invading every road. The Commander-in-Chief '''Dāshībǎ''' （'''搭失把'''） sent armed forces to the capital but was unable to. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) annexed further circuits and dispatched his son '''Mǎnsàn''' ('''滿散''') to the imperial court to offer terms of service. Although they accepted tribute and the official calendar of the Ming dynasty, their clothes and administration resembled that of a monarchy. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) died, his son Zhāo bìngfā ('''昭併發'''; Hsö Pem Hpa) was established. Eight years later it passed to '''Táibiǎn''' ('''臺扁''';  Hsö Siu Hpa). A year later, '''Táibiǎn's''' ('''臺扁''';  Hsö Siu Hpa) uncle '''Zhāo xiàofā''' ('''昭肖發'''; , Hsö Kap Hpa) killed him himself and seized power. A year later, bandits killed '''Zhāo xiàofā''' ('''昭肖發'''; Hsö Kap Hpa) and established his younger brother '''Sīwǎfā''' ('''思瓦發'''; Hso Vau Hpa) [as ruler].
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|In the current dynasty, in the 58th year (Xinyou) of the Hongwu Emperor ('''1381 A.D.''')
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}
===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>521ho3mbscwkusyrtbvzn72sbednxad</sha1>
    </revision>
    <revision>
      <id>4669869</id>
      <parentid>4669860</parentid>
      <timestamp>2026-09-13T09:29:54Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Introduction */</comment>
      <origin>4669869</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="34175" sha1="4qm4w9hf0ffomjwiio4rgg1vww2jplf" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|In Emperor Xianzong's 3rd year in the Yuan Dynasty, Emperor Shìzǔ (世祖; Kublai Khan) entered '''Lìjiāng''' ('''麗江''') from Tibet and himself in '''Yèyú''' ('''葉榆'''; Present Day Dali) brought peace to Yunnan. The following year, [he] commanded General UriyangKhadai to pacify the barbarian lands. The region was transformed into twenty circuits, four prefectures, forty-four districts and twenty-six departments, each with indigenous officials overseen by the Gold Teeth Commander in Chief.&lt;ref&gt;A Tai Shan Leader likely.&lt;/ref&gt; Officials were appointed to administer certain lands, returning by spring to avoid malarial miasma.
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|In the the 8th year of the Zhizheng era ('''1348 AD''')  Lùchuān (麓川) indigenous chief '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) had been countlessly harassing and invading every road. The Commander-in-Chief '''Dāshībǎ''' （'''搭失把'''） sent armed forces to the capital but was unable to. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) annexed further circuits and dispatched his son '''Mǎnsàn''' ('''滿散''') to the imperial court to offer terms of service. Although they accepted tribute and the official calendar of the Ming dynasty, their clothes and administration resembled that of a monarchy. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) died, his son Zhāo bìngfā ('''昭併發'''; Hsö Pem Hpa) was established. Eight years later it passed to '''Táibiǎn''' ('''臺扁''';  Hsö Siu Hpa). A year later, '''Táibiǎn's''' ('''臺扁''';  Hsö Siu Hpa) uncle '''Zhāo xiàofā''' ('''昭肖發'''; , Hsö Kap Hpa) killed him himself and seized power. A year later, bandits killed '''Zhāo xiàofā''' ('''昭肖發'''; Hsö Kap Hpa) and established his younger brother '''Sīwǎfā''' ('''思瓦發'''; Hso Vau Hpa) [as ruler].
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|In the current dynasty, in the 58th year (Xinyou) of the Hongwu Emperor ('''1381 A.D.'''), Yunnan was pacified. The next year, '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) plundered the Gold Teeth barbarians. That winter, '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) captured the territory of '''Zhělán''' ('''者闌''') and '''Nándiàn''' ('''南甸'''). His subordinate '''Dálǔfāng''' （'''達鲁方'''）placed '''Mǎnsàn's''' ('''滿散''') son, '''Sīlúnfā''' ('''思侖發'''; Hsö Hom Hpa) as ruler and killed '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) when outside. The offered tribute included white elephants, rhinoceroses, horses and other local products. The palace could not bear to cut ties with outside spheres of influence and commanded the Fujian Left Vice Official '''Wáng Dùn''' ('''王鈍''') to lead in the checking of the city walls of Yunnan, order discussions of pros and cons of allegience, discuss the annual tribute rate and secured their submission. He conferred '''Sīlúnfā''' ('''思侖發'''; Hsö Hom Hpa) as the Burma Pacification Commissioner. In the third year ('''1386 A.D.'''), he returned to invade '''Jǐngdōng''' ('''景東'''). The next year, his subordinate '''Diāosīlǎng''' ('''刁思朗''') invaded '''Dìngbiān''' ('''定邊'''). The Emperor ordered Marquis of '''Xīpíng''' ('''西平''') '''Mù yīng''' ('''沐英''')  to lead an army to defeat him where he caught '''Diāosīlǎng''' ('''刁思朗'''). The barbarians became fearful and submitted. In order not to restrict those far-away peoples, the official system and administration were all in their customs.
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}

===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>4qm4w9hf0ffomjwiio4rgg1vww2jplf</sha1>
    </revision>
    <revision>
      <id>4669875</id>
      <parentid>4669869</parentid>
      <timestamp>2026-09-13T09:57:02Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Introduction */</comment>
      <origin>4669875</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="35398" sha1="6eulnpvzksi6fpiv4f3h1rytnfka09x" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Baiyi Zhuan (百夷傳)
 | author   = Qian Guxun (錢古訓)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    = The Baiyizhuan, or, '''Biography of 100 Barbarians''', was compiled by Qian Guxun (錢古訓) with Li Sicong (李思聪) and sent to the Ming Dynasty but never formally published yet stored away. Copies emerged under both names however, most agree that both envoys wrote their own accounts of Myanmar to control the issue of Shan Kings on the borders. This version is attributed to Qian Guxun and sourced from Wikisource.   
}}

== Front Matter ==

# [[Baiyi Zhuan/Translator's Note|Translator's Note]]
# [[Baiyi Zhuan/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Premable to the purpose and context of the document and political situation. 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|百夷，在雲南西南數千里，其地方萬里。景東在其東，西天古刺在其西，八百媳婦在其南，吐番在其北；東南則車里，西南則緬國，東北則哀牢〈（今之金齒衛也）〉，西北則西番、回紇。
|[The] One Hundred Barbarians are a few thosand '''Lǐ''' ('''里''') southwest of Yunnan. There region is very far away. '''Jǐngdōng''' ('''景東''') is east of them. The western regions Gǔ cì (古刺) [people] are west of them. South of them are the '''Eight Hundred Xífù''' ('''八百媳婦'''; Laos). North of them is Tibet. Southeast of them is Chē lǐ (車里), southwest is Burma, Northeast is '''Āiláo''' ('''哀牢''')&lt;ref&gt;The ancient tribal confederation of the Yongchang-Gaoligong area.&lt;/ref&gt; Today, these are the gold tooth people. Northwest of them is 
Western Barbarians and '''Huíhé''' ('''回紇'''; Uyghur people).

|-
|俗有大百夷、小百夷、漂人、古剌、哈剌、緬人、结些、吟杜、弩人、蒲蠻、阿昌等名，故曰百夷。
|The customs of Greater One Hundred Barbarians, the Lesser One Hundred Barbarians, Pyu people, Gǔ cì (古刺) [people], Hā cì (哈刺) [people], Burmese people, '''jiēsuò''' （'''结些''')&lt;ref&gt;There is reason to believe that these may be the Zo people. The Jie however is difficult to understand, likely a terminology transfer issue from intermediaries. Like the Mosuo people, I suggest this to be read as Jie Suo. If so, this would be the earliest mention of Zo terminology since Vincent Sangermono.&lt;/ref&gt;, '''Yíndù'''（'''吟杜''')&lt;ref&gt;These are only mentioned once in the document. Whether it's a mix-up with Hadu, or referring to Indians, is unknown.&lt;/ref&gt;, Nǔ people (弩人; crossbowman people),  Pú (蒲) and Āchāng (阿昌), among others, can be spoken of as the One Hundred Barbarians.
|-
|漢以前未嘗通中國，諸葛亮征蠻，亦抵怒江而止。唐天寶中，夷人始随爨歸王入朝。其眾各有部領，不相統屬。
|Before the Han dynasty, they had no contact with China.&lt;ref&gt;The main exception may be the Ailao people.&lt;/ref&gt; '''Zhūgé liàng''' ('''諸葛亮''') went on an expedition against the barbarians, where he stopped right up against the '''Nùjiāng River''' ('''怒江'''). During the Tianbao Era of the Tang Dynasty, the barbarians began to follow the '''Cuàn''' ('''爨''') and '''Guī''' ('''歸''') clan leaders.&lt;ref&gt;The '''Cuàn''' ('''爨''') eventually founded the Kingdom of Nanzhao, which ruled powerfully in the region, competing with Tibet and Tang China.&lt;/ref&gt;  The people had their own leaders and were not unified.


|-
|元憲宗三年，世祖由吐番入麗江，自葉榆平至雲南〈（葉榆即大理也）〉。明年，命將兀良哈臺征降夷地。遂分为路二十、府四、甸四十有四、部二十有六、各設土官，置金齒都元帥府領之。有所督，委官入其地，交春即還，避瘴气也。
|In Emperor Xianzong's 3rd year in the Yuan Dynasty, Emperor Shìzǔ (世祖; Kublai Khan) entered '''Lìjiāng''' ('''麗江''') from Tibet and himself in '''Yèyú''' ('''葉榆'''; Present Day Dali) brought peace to Yunnan. The following year, [he] commanded General UriyangKhadai to pacify the barbarian lands. The region was transformed into twenty circuits, four prefectures, forty-four districts and twenty-six departments, each with indigenous officials overseen by the Gold Teeth Commander in Chief.&lt;ref&gt;A Tai Shan Leader likely.&lt;/ref&gt; Officials were appointed to administer certain lands, returning by spring to avoid malarial miasma.
|-
|至正戊子，麓川土官思可發數侵扰各路，元帥搭失把都討之，不克。思可發益吞并諸路，而遣其子滿散入朝，以輸情款。雖奉正朔，納職貢，而服用制度，擬於王者。思可發死，子昭併發立。八年，傳其子臺扁。踰年，臺扁從父昭肖發殺之而自立，期年，盗殺昭肖發，眾立其弟思瓦發。
|In the the 8th year of the Zhizheng era ('''1348 AD''')  Lùchuān (麓川) indigenous chief '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) had been countlessly harassing and invading every road. The Commander-in-Chief '''Dāshībǎ''' （'''搭失把'''） sent armed forces to the capital but was unable to. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) annexed further circuits and dispatched his son '''Mǎnsàn''' ('''滿散''') to the imperial court to offer terms of service. Although they accepted tribute and the official calendar of the Ming dynasty, their clothes and administration resembled that of a monarchy. '''Sī kě fā''' ('''思可發'''; Hsö Hkan Hpa) died, his son Zhāo bìngfā ('''昭併發'''; Hsö Pem Hpa) was established. Eight years later it passed to '''Táibiǎn''' ('''臺扁''';  Hsö Siu Hpa). A year later, '''Táibiǎn's''' ('''臺扁''';  Hsö Siu Hpa) uncle '''Zhāo xiàofā''' ('''昭肖發'''; , Hsö Kap Hpa) killed him himself and seized power. A year later, bandits killed '''Zhāo xiàofā''' ('''昭肖發'''; Hsö Kap Hpa) and established his younger brother '''Sīwǎfā''' ('''思瓦發'''; Hso Vau Hpa) [as ruler].
|-
|國朝洪武辛酉，平雲南。明年，思瓦發寇金齒。是冬，思瓦發略于者闌、南甸。其屬達鲁方等輙立滿散之子思侖發，而殺思瓦發於外。即譴使貢白象、犀、馬、方物於朝。廷議不忍絕以化外，乃命福建左參政王鈍率雲南部校郭京美等，諭以向背利害，約以每歲貢獻之率，而遂内附。於是授思侖發为麓川平緬軍民宣慰。丙寅，復寇景東。明年，部屬刁思朗犯定邊，天子命西平侯沐英總兵敗之，獲刁思朗，夷人懼服。上以遠人不加約束，故官稱制度皆從其俗。
|In the current dynasty, in the 58th year (Xinyou) of the Hongwu Emperor ('''1381 A.D.'''), Yunnan was pacified. The next year, '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) plundered the Gold Teeth barbarians. That winter, '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) captured the territory of '''Zhělán''' ('''者闌''') and '''Nándiàn''' ('''南甸'''). His subordinate '''Dálǔfāng''' （'''達鲁方'''）placed '''Mǎnsàn's''' ('''滿散''') son, '''Sīlúnfā''' ('''思侖發'''; Hsö Hom Hpa) as ruler and killed '''Sīwǎfā''' ('''思瓦發'''; Hsö Vau Hpa) when outside. The offered tribute included white elephants, rhinoceroses, horses and other local products. The palace could not bear to cut ties with outside spheres of influence and commanded the Fujian Left Vice Official '''Wáng Dùn''' ('''王鈍''') to lead in the checking of the city walls of Yunnan, order discussions of pros and cons of allegience, discuss the annual tribute rate and secured their submission. He conferred '''Sīlúnfā''' ('''思侖發'''; Hsö Hom Hpa) as the Burma Pacification Commissioner. In the third year ('''1386 A.D.'''), he returned to invade '''Jǐngdōng''' ('''景東'''). The next year, his subordinate '''Diāosīlǎng''' ('''刁思朗''') invaded '''Dìngbiān''' ('''定邊'''). The Emperor ordered Marquis of '''Xīpíng''' ('''西平''') '''Mù yīng''' ('''沐英''')  to lead an army to defeat him where he caught '''Diāosīlǎng''' ('''刁思朗'''). The barbarians became fearful and submitted. In order not to restrict those far-away peoples, the official system and administration were all in their customs.
|-
|其下稱思侖發曰『昭』，猶中國稱君主也。所居麓川之地曰者闌，猶中國稱京師也。其屬則置『叨孟』以總統政事，兼領軍民。『昭錄』領萬餘人，『昭綱』領千餘人，『昭伯』領百人；領一伍者为『昭哈斯』，領一什者为『昭准』；皆屬於『叨孟』。又有『昭錄令』，遇有征调，亦與『叨孟』統軍以行。其近侍呼为『立者』，閽寺呼为『割斷』。大小各有分地，任其徭賦。
|'''Sīlúnfā''' ('''思侖發'''; Hsö Hom Hpa) is called '''Zhāo''' ('''昭'''), like how China uses &quot;Lord&quot;. '''Lùchuān's''' ('''麓川''') [ruler's] dwelling place is called '''Zhělán''' ('''者闌'''), like how China uses the term &quot;Capital&quot;. Their subordinates are known as '''Dāomèng''' ('''叨孟'''), who generally handled political affairs while simultaneously leading the military and civilians. '''Zhāolù''' ('''昭錄''') led over ten thousand households, '''Zhāogāng''' ('''昭綱)''' led over a thousand households, '''Zhāobó''' ('''昭伯''') led a hundred households. Those who led five soldiers were known as '''Zhāohāsī''' ('''昭哈斯'''), those who led ten soldiers were known as '''Zhāozhǔn''' ('''昭准'''). Each [of these] were part of the  '''Dāomèng''' ('''叨孟'''). There is also '''Zhāolùlìng''' ('''昭錄令''') who also happen to carry out conscription for the '''Dāomèng''' ('''叨孟''') to gather an army to lead. Their attendants were known as '''Lìzhě'''（'''立者'''). Doorkeepers of Buddhist temples were called '''Gēduàn''' ('''割斷'''). Big or small each had distributed land appointed and endowed to them as compulsory servicefor corvee and taxes.
|-
|上下僭奢，雖微職亦繫鈒花金銀帶。貴賤皆戴筍籜帽，而飾金寶於頂，如浮圖狀，懸以金玉，插以珠翠花，被以毛纓，綴以毛羽。貴者衣綺麗。每出入，象馬僕從滿途。象以銀鏡數十聯綴於羈靮，緣以銀釘，鞍上有闌如交椅狀，藉以裀褥，上設錦障蓋，下懸銅響鈴，坐一奴鞍後，執長鉤驅止之。遇貴於己者，必讓途而往。凡相見必合掌而拜，習胡人之跪。長於己者必拜跪之，言則叩頭受之。叨孟以下見其主，則膝行以前，二步一拜，退亦如之。執事於貴人之側，雖跪終日無倦狀。貴人之前過，必磬折鞠躬。宴会則貴人上坐，其次列坐於下，以逮至賤。先以沽茶及蒌葉、檳榔啖之（沽茶者，山中茶葉，春夏間采煮之，實於竹筒内，封以竹箬，過一二歲取食之，味極佳，然不可用水煎飲）。次具飯，次進酒饌，俱用冷而無熱。每客必一仆持水瓶側跪，俟嗽口盥手而後食。食畢亦如之，而後起。客十則十人各行一客。酒或以杯，或用筒（筒以蕨楷，或用鵝翎管連贯，各長丈餘，漆之而飾以金，假若一酿酒，則漬以水一滿瓮，插筒手中，立標以驗其盏數，人各以次舉筒咂之。咂酒一盏，仍漬水一盏，傳之次客，味甚佳，至淡，水方止，俗呼为咂酒）。酒與食物必祭而後食，食不用筯。酒初行，一人大噪，眾皆合之，如此者三，乃舉樂。樂有三等：琵琶、胡琴、等笛、響盏之類，效中原音，大百夷樂也。笙阮、排簫、箜篌、琵琶之類，人各拍手歌舞，作緬國之曲，緬樂也。銅饒、銅鼓、響板、大小長皮鼓，以手拊之，與僧道樂頗等者，車里樂也。村甸間擊大鼓，吹芦笙，舞干为宴。長者授卑賤酒食，必叩頭受之，易以他器而食。食畢，仍叩頭而退。
|
|-
|凡貿易必用銀，雜以銅，鑄若半卵狀，流通商賈間。官無倉庾，民無税粮。每年秋季，其主遣亲信部屬往各甸，计房屋征金銀，谓之取差發（房屋一間，大者征銀一两、三两，小者一两而止）。無中國文字，小事刻竹木，大事作緬书，皆旁行为记。刑名無律，不知鞭挞，轻罪則罚，重罪則死。或殺，或用人扱殺。或用象打，或投於水，或以绳帛缢。男婦不敢为奸盗，犯則殺之。
|
|-
|所居無城池濠隍，惟编木立寨，貴賤悉构以草楼，無窗壁门户，时以花布障围四壁，以蔽风雨而已。邮傅一里設一小楼，數人守之，公事雖千里遠，报在顷刻。無軍民之分，聚則为軍，散則为民。遇有战斗，每三人或五人出軍一名，择其壮者为正軍，呼为『锡剌』。锡剌持兵御敌，余人荷所供。故軍行五六萬，战者不滿二萬。兵行不整，先後不一。多以象为雄势，战則缚身象上。裹革兜，被銅铁甲，用長镖干弩，不習弓矢。征战及造作用事，遇日月食則罢之，毁之。
|
|-
|所用多陶器，惟宣慰用金銀玻璃，部酋間用金銀酒器。凡部酋出，其器用、仆妾、财寶之類皆随之，從者千余，昼夜随所适，必作宴笑樂。
|
|-
|男子衣服多效胡服，或衣宽袖長衫，不识裙袴。其首皆髡，胫皆黥。不髡者殺之，不黥者眾叱笑，比之婦人。婦人髻绾於後，不谙脂粉，衣窄袖衫，皂統裙，白裹頭，白行缠，跣足。其俗賤婦人，貴男子，耕织徭役担负之類，雖老婦亦不得少休。嫁娶不分宗话，不重处女。年未笄，听與男子私，從至其家，男母为之濯足，留五六昼，遣歸母家，方通媒妁，置财礼娶之。凡生子，貴者浴於家，賤者浴於河，數日，授子於夫，仍服劳無倦。酋長妻數十，婢百余，不分妻妾，亦無鮅忌。男女浴於河，雖翁婦叔嫂，相向無耻。子弟有職名，則受父兄跪拜。父母亡，用婦祝尸，亲邻咸馈酒肉，聚年少环尸歌舞宴樂，婦人擊碓杵，自旦達宵，數日而後葬。其棺若馬槽，無蓋，置尸於中，抬往葬所，一人執刀持前导。及瘗，其生平所用器物，坏之於側而去。
|
|-
|}

===Ethnic Groups and customs===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ A list of ethnic groups encountered and their traditions and general customs.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其俗，不祀先，不奉佛，亦無僧道。小百夷居其境之東北邊，或学阿昌，或学蒲蠻，或仿大百夷，其習俗不一。
|Their customs do not offer sacrifices [to ancestors], do not revere the Buddha. There are no Buddhists and Daoists [among them]. The Lesser One Hundred Barbarians reside on the northeast border, following Āchāng ('''阿昌''') customs, following Pú ('''蒲''') customs and some imitate the Greater One Hundred Barbarians. Their customs are not the same (uniform).
|-
|車里，亦谓小百夷，其俗刺额、黑齒、剪發，狀如頭陀。
|[The people of] '''Chē lǐ''' ('''車里''')&lt;ref&gt;'''Chē lǐ''' ('''車里''') refers to the Cheli Military and Civilian Pacification Commissioners Office. It was a Tai State that located at Jinghong City in modern day Xishuangbanna in Yunnan.&lt;/ref&gt;, are also called Lesser One Hundred Barbarians. Their customs are tattooing foreheads, blackening teeth and cutting hair. Appearing as if like ascetic monks.
|-
|哈刺，男女黑真黑。男子以花布为套衣，亦有效百夷制者；婦人髻在後，项系雜色珠，以娑罗布披身上为衣，横系於腰为裙（娑罗布即中國木棉布，坚厚，或织以青红纹）。仍环黑藤數百围於腰上，行缠用青花布，赤脚（蒲蠻、阿昌，事見《雲南志》）。
|'''Hā cì''' ('''哈刺'''), men and women are [both] black, truly black. Men use printed cloth&lt;ref&gt;g&lt;/ref&gt; for covering themselves, also which the One Hundred bararians effectively manufacture; married women have top knots behind [their head]. It is tied at the back of their neck with various pearls and beads. '''Suō luó''' ('''娑罗''')&lt;ref&gt;'''Sarong''' today, however this appears to be a complex term with many copyediting issues historically, Brahmin drapes, Suoluolong, eventually describing a type of silk-cottob robe made from plant materials.&lt;/ref&gt; are draped around their bodies as clothes, horizontally it connected at the waist and lower back as a skirt. ('''Suō luóbù pī''' ('''娑罗布披''') namely is the Chinese Cotton Tree (Bombax Ceiba) cloth, strong and thick, possibly weaved as blue, red patterns.) Yet it encircles black rattan several hundred times, wrapped at the waist and lower back, it wraps around [their leg] to be used as a blue printed cloth [as they're] barefoot. 

([Used amongst the] Pú mán (蒲蠻), āchāng (阿昌), shì jiàn (事見); [according to the] The Yunnan Gazeteer&lt;ref&gt;Written by Fan Chuo of the 9th century, also known as 蛮书 (Barbarian Document)&lt;/ref&gt;.)


|-
|古刺，男女色甚黑。男子衣服装飾類哈刺，或用白布为套衣。婦人如罗罗狀（罗罗見《雲南志》）。
|'''Gǔ cì''' ('''古刺''') [people] are coloured extremely black. The men's clothes, decorations and adornments closely resembled the '''Hā cì''' ('''哈刺'''), and they use white cloth as [outer] covering garments. Married women resemble the '''Luó luó''' ('''罗罗''') [people]. ([For the] '''Luó luó''' ('''罗罗''') see The Yunnan Gazeteer.)
|-
|漂人，男女衣服皆類百夷。婦人以白布缠頭，衣露腹，以红藤缠之，娑罗布为裙，两接，上短下長，男女同耕。
|Pyu people&lt;ref&gt;This is the last time a document mentions the existence of Pyu people, namely. The Burmese stopped mentioning them by the 12th century, as did the Persians in the 10th century. Their retention of it suggests that absorption was slower and that the Burmese and Pyu were still distinct, according to the envoys.&lt;/ref&gt;, [the] men and women's clothes all resemble the One Hundred Barbarians. Married women wear white cloth wrapped around their head, their clothes expose their stomach/ naval. By means of red rattan winding around them, the '''Suō luó''' ('''娑罗''') [is worn] as a skirt. Two [cloths] connect, upper [cloth] is short, bottom [cloth] is long. Men and women [both] till [the fields].
|-
|緬人，色黑類哈刺，男女頭上以白布缠高三四尺，衣大袖白布衫，腰以下一布通前後便缠之，貴者布長二丈余，賤者不一丈。甚善水，嗜酒。其地有树，狀若棕，树之杪有如筍者八九茎，人以刀去其尖，缚瓢於上，過一宵則有酒一瓢，香而且甘，飲之輙醉。其酒经宿必酸，炼为烧酒，能飲者可一盏。有为僧者，以黄布为袈裟，袒右手，戒行極精，午後不飲食。婦人貌陋甚淫，夫少不在，則與他人私，遂为夫婦。以白布裹頭而披花为衣。
|Burmese people, [their] colour is black like the '''Hā cì''' ('''哈刺'''). Men and women [both] on their heads have white cloth wrapping around it [aproximately] as long as three to four '''Chǐ''' ('''尺''';1.2 m-1.36 m). Their clothes are large-sleeved white cloth garments. Below the waist and lower back, one cloth goes all around to be wrapped around them. Expensive cloth is as long as two '''zhàng''' ('''丈'''; 6.2m-6.8m). Inexpensive [cloth] is not even one '''zhàng''' ('''丈'''; 3.1m-3.4m). They are extremely well-disposed to water and fond of wine. On their land, their trees appear as palm trees. They cultivate eight to nine stalks, with the tips of the leaves resembling bamboo shoots. The people take knives and cut off the tips. They bind a dried gourd ladle to it. After one night, it becomes a gourd of wine, fragrant and sweet to drink to intoxication. Their wine, undergoing [another] night, certainly becomes bitter; it gets refined into '''Shāojiǔ''' ('''烧酒''')&lt;ref&gt;A famous Tang Dynasty wine beverage.&lt;/ref&gt;. [Heavy] drinkers can only drink one small cup. There are monks. Yellow cloth is used as Kasaya robes (Buddhist robes) with the right arm remaining bare. They strictly adhere to the utmost discipline. They do not eat or drink in the afternoon. Women's appearances are excessively plain, and they are promiscuous. If husbands are away briefly, they enter into relations with other men and succeed as a married couple. White cloth is wrapped around their head and draped on their shoulders in a printed way.
|-
|哈杜，巢居山林，無衣服，不识农业，惟食草木禽兽，善骑射。冷則抱巨石，山坡間往復奔走，以汗出为度。
|'''Hā dù''' ('''哈杜''') [people] reside in nests in mountain forests; they do not wear clothes. They have no knowledge of agriculture. Only eating vegetation and birds and creatures. They are adept at horses and archery. [When] cold, they grab a boulder and make running trips back and forth between mountainsides until they perspire out to the temperature.


|-
|弩人，目稍深，貌尤黑，额颅及口邊刺十字十余。
|'''Nǔ''' people ('''弩人'''; crossbowman people), [have] deep-set eyes, [their] appearance is outstandingly dark. Their forehead and mouth edges are tattooed with crosses more than ten times.
|-
|有结些者，從耳尖連颊皮破，以象牙为大圈，横贯之，以花布裹頭，而垂余布於後，衣半身衫，而袒其肩。婦人未详。其人居戛璃者多。
|[There] is some knotted &quot;Zo&quot; people&lt;ref&gt;This translation is messy. However, it is the first use of the Zhexie/Jiexie term, which was popularised during the Qing era. However, this early, 些 Xie was actually Suo, like the Mosuo people. Hence, the name appears to be a misrendering of Zo people from an intermediary translator, possibly.&lt;/ref&gt;, from the tips of the ears to the cheeks, the skin is pierced. Using ivory as a large ring, they pass it horizontally through [the pierced skin]. Printed cloth is wrapped around the head and hangs down onto their back as a partially wrapped robe and bears their shoulders. Nothing is known/reported concerning the women.&lt;ref&gt;Likely possibly meaning that the women are indistinguishable from men. An observation echoed by the British of the Zo people during the colonial era.&lt;/ref&gt;. Many of these people habitat at '''Kalay'''. 
|-
|諸夷言语習俗雖异，然由大百夷为君長，故各或效其所为。夷人有名不讳，無姓。
|Although the various barbarian languages and customs are different, they follow the Greater One Hundred Barbarians as their central ruler. Therefore, possibly each group imitates that they do. The Yi people have names but observe no naming taboos; they have no surnames.
|-
|無医卜等书。不知时节，惟望月之盈亏为候。有事惟鸡卜是决。疾病不知服药，以姜汁注鼻中。病甚，命巫祭鬼路側，病疟者多愈，病熱者多死。地多平川沃土，民一甸率有數十千户，眾置貿易所，谓之街子。婦人用锄地，事稼穑，地利不能尽，然多产牛、羊、鱼、果。
|There are no books on medicine and divination. They are unaware of seasons. Only the moon in its waxing and waning is observed. For matters, a chicken is used for divination. For diseases they do not know how to take medicine. They pour ginger juice into their noses. For extreme sickness, the shaman offers spirit sacrifices next to the road. Those suffering from malaria are likely to recover. Those with a fever are more likely to die. The land is flat with plains and fertile, the people of a district can lead up to ten thousand households. They install commercial trade posts known as ''street markets'' ('''街子'''; Jiē zǐ). Women hoe and weed the soil and [attend] matters to do with sowing and reaping. The productivity of land cannot be exhausted, as there are many ox, sheep, fish and fruits.
|-
|其气候：春夏雨，秋冬晴，腊月亦如春，昼暄夜冷，晓多烟雾，無霜，春秋烟瘴甚盛。
|Their climate: In spring and summer, it rains. In autumn and winter, it is clear. In the 12th Lunar month ('''December-Feburary''') it feels like spring. The daytime is warm, and the nighttime is cold. At dawn, there is a lot of fog. They have no frost. Spring and Autumn miasma carries an excessive level of malaria.
|-
|其飲食之异者：鳅、鳝、蛇、鼠、晴蜓、虫负、蛟、蝉、蝗、蚁、蛙、土蜂之類以为食；鱼肉等汁暨米汤信宿而生蛆者以为飲。
|Their food and drink are unusual in the following ways. Loach, eels, snakes, dragonflies, insects, aquatic animals, cicadas, locusts, ants, frogs, and scoliod wasps are all types of food. They drink the juice of fish, meat, and rice gruel, which, over two nights, gain maggots, which are eaten.
|-
|其草木禽兽之异：草則秋間數十百株结为一聚，地产此草，烟瘴尤甚。树木多有三四株结为連理。有大如斗之柑，有鲇頭鲤身之鱼，水牛頭黄牛身之牛，绵羊頭山羊身之羊。雄鸡多伏卵，亦有生卵者。者闌有一池，沸如汤，人多投肉熟之。
|Their plants and animals are unusual: in autumn, their grass joins from hundreds of stalks to cluster. The land these grasses grow on has an excessively strong malarial miasma. Trees often produce multiple stumps in a fusion. There are large tangerines as large as dippers. There is [a] fish with a sheatfish head and carp bodies. There are oxen with water buffalo heads and yellow ox bodies. There are sheep with sheep heads and mountain goat bodies. Roosters brood over eggs, there are also [males] that lay eggs. At '''Zhě lán''' ('''者闌''')&lt;ref&gt;On the Shan Myanmar and China border near Muse.&lt;/ref&gt;, [the size of] ponds for boiling soup. People often cast mature meat in it. 
|-
|境内所产珍物：雅琥、琥珀、犀、象、鹦鹉、孔雀、鳞蛇、脑、麝、阿魏、金、銀、玻璃之類。
|Within its borders are the following precious items it produces: elegant amber, amber, rhinoceros, elephant, parrots, peacocks, snake scales, brains, musk deer, Resina Furelae, gold, silver, glass types of products. 
|-
|其山水险隘。北有高良弓山，横亘二百余里，高五十余里，與怒江相倚。西有馬安山，山有一关，若一人守关，萬夫难入。東为麓川江，可通舟楫。南與金沙江合而入於西海。南下交趾界。金沙江之南，有東胡、得冷、緬人三國。緬之西即西天也。
|The mountains have narrow, dangerous river passes. North there is the Gaoligong Mountains, it horizontally extends two hundred '''Lǐ''' ('''里'''), and is tall as five hundred '''Lǐ''' ('''里''') right next to the '''Nùjiāng''' ('''怒江'''). West is the '''Mǎ'ān Mountain''' ('''馬安山'''). The mountain has one mountain pass. If one person guards the pass, then ten thousand will struggle to enter. East is the '''Lù chuān River''' ('''麓川江'''). You can pass it in an oarboat. South is the '''Jīnshā River''' ('''金沙江''') which enters at the western sea. South it borders '''Jiāozhǐ''' ('''交趾'''; Vietnam). Further south of the '''Jīnshā River''' ('''金沙江''') are the three polities, which has '''Dōnghú''' ('''東胡'''； Eastern Barbarians), '''Dé lěng''' ('''得冷'''; Derung people) and '''Miǎn people''' ('''緬人'''; Burmese people). West of Burma lies the Western Regions&lt;ref&gt; A term for India and Central Asia, which were Buddhist.&lt;/ref&gt;.

|-
|緬國古舍利國，又名狮子國，多佛塔。緬國與夷連歲横兵。洪武之亥冬，緬人诉於朝。丙子春，皇帝遣臣古训及桂阳李思聪至两國，諭以睦邻之义。
|Burma, formerly the '''Shèlì country''' ('''舍利'''), also known as the Lion Country, is filled with pagodas. Burma and the Yi Barbarians were in continuous warfare for years. During the reign of the Hongwu Emperor in the winter of the year of the boar ('''1395 A.D.'''), Burma issued a royal complaint. In Spring of the Year of the Rat, ('''1396 A.D.'''), the Emperor dispatched official Guxun and Li Cong of Guiyang to the two countries to order them to get on well as neighbours with righteousness.
|-
|}

===Statements and Relations between the Kingdoms===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Outcome of the envoys mission and political relations between Shans and Burmese.
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|其諭緬國王曰：
|
|-
|『里路险遠，山川阻修，风殊俗异，此乃天造地設也。尔能勤使者，涉险遠，越邻邦以至中夏，其使者之难，冲烟突雾，晨進昏止，饥餐渴飲，吞吐烟岚，异风霜而方至。其为使者，不亦难乎！古人有云：诚君子將有事於遠，友千里之外，神交而志通。今萬里之外，尔能勤使而至，遠修其好，美絕古而惟今。然排难解纷之事，朕之旨意，恨不一言而正，使彼此各罢兵守，樂黎民於市野，民居共处，砃相邻而同井飲，籍雖两國之民，居处难分，惟存关市有讥，是其和也。若尔緬不主衅，夷不强凌，如此，雖弱自保，以奉天道。其或不听朕命，忿争不已，天將昭鉴，福善祸淫，迟速可待。鯩至，朕不多诫。但诚可以交天人，尔其审之，母忘朕諭。』
|
|-
|諭思侖發曰：
|
|-
|『朕中國先古圣人，驭顽礼德，各有条章。是条章也，列圣相继，守而行之，上下相安，黔黎樂业。何也？諸侯敬畏，世禄子孙，國祚绵長，乃九伐之功驗也。列國敢有凭弱犯寡者，天子發兵以眚之；贼贤害民者，亦發兵以伐之；暴内凌外，則兴師以坛之；野荒民散，則用兵以削之；负固不服，則舉兵以侵之；贼殺其亲，則正其罪以殺之；放弑其君，則明其罪以诛之；犯令凌政，則杜而絕之；内外乱，鸟兽行，則殄灭之。九伐之征如是也。尔思侖發，以中國较之，合问凭弱犯寡之由。何以見？歲以兵寇車里，不时侵掠八百，恃强犯緬；戛璃國小民寡，而已平之，斯说也，不過告诫之词。中國周临四夷，與諸酋長地里相接，居民亦相密迩，如此者，耳闻之邦若干，目擊之邦若干，朕未嘗恃强凭凌，絕灭其嗣者。雲南之地，已为我有，似乎尚强以取之，非也！乃元世子孙梁王者，恃元之苗裔，匿我有罪，納我逋逃，诱我邊守，是乃不得已而發问罪之師，非無故而兴師。此乃元运天更，其苗裔不当安处。况生事於我邻邦，其理势使然，夷如反掌。尔麓川之蠢，初擅兴金齒之役，次谋景東而寇定邊，理当大發精兵而较胜负。朕释而不较，未嘗强尔为約束之邦，听尔自为声教，今又几年矣。近闻蚕食邻邦，意在扩土地而擅有其眾，又將为我西南之役。噫，未可！古中國圣人有云：‘山川地理人物之類，乃神器也，非人强有，必天授然後得之’。尔思侖發不修邻邦之好，三面發兵，蚕食諸國，其贪也如是，其谋也如是。彼麓川周临之國，始古至今，各有主者，未嘗吞并。朕雖不能止尔，听尔自为，果天道使然，尔以人事应之，或为而可。噫！以朕戒尔守全則可，不守全而以全动，設若全亏，是为全亡，莫如守全以圖绵長，不亦美乎？』
|
|-
|由是二國罢兵和好。
|
|-
|时古训等适遇百夷其部下酋長曰刀干孟者叛其國，余等以大义諭其部眾，而叛者闻之稍却。於是，思侖發欲留余等以为援，且進以金寶象馬等物，故余以书示之曰：
|
|-
|『吾闻君上有怀遠之德，遠臣有敬上之心，始古迄今，莫违此义。夫君居九重之上，雖欲顷刻目尔遠臣，未可得也，臣处萬里之外，即欲朝暮身亲君上，亦未易得也。故朝廷有將命之官，使之宣德布威；而遠方有承命之宜，期其輸忠納款。今天子应天顺民，奉天为治，四维八極，尽为臣妾，無有专擅，不敢违逆。西南一区，夷酋亦眾，惟尔麓川，多蒙恩宠，既受以官，復加以服。况贤王亲临尔境，而德惠數及尔身。为尔计，則將度其心，量其才，何为而可以尽忠天子，何为而可以致敬贤王，又何为而可以安邊境而不干天怒，又何为而可以教百姓而不违法度？借曰邊境不安，必思曰，我事上未忠或未至，而眾不服我耶？百姓违法，必思曰，我守職已或有僭而民亦犯上耶？於是我則尽其忠，去其僭，如此，則邊境自安，人民從教矣。且吾以尔目擊效驗明之：往年思瓦發不服朝廷，轻犯金齒，天子雖未问罪，天則假手於達鲁方等，而思瓦發被戮。刀思朗不從尔命，窃寇定邊，尔雖未能息其兵，天則助威於我邊將，而刀思朗等即灭。惟尔知天命，達人理，故能享天禄，守人爵。迩来天子恐尔所为，或涉放肆，特敕諭以戒之；贤王恐尔無知，或生疑懼，特令旨以恤之。此恩此德，穷天極地。尔之披肝露胆，开心見诚，吾尽見矣；尔之尊重朝廷，敬奉殿下，告亦見矣。今尔固留吾辈，其意本美。近者尔甸寨少宁，刀干谋异，吾將回朝为尔明白其事，尔乃留我，使我不速還朝，假如刀干鸣尔留难天使之非於朝，則反误尔敬君之心矣。且尔赠以金、銀、裀褥、馬、象等物，吾固不受者，非見怪也，實相爱也。何則？朝廷恩尔，抚安尔邦，未嘗令使者取货於尔也。夫货财，饥不可以充口，疾不可以救死。况中國金玉成山，象馬若蚁，未以为寶也，惟所寶者，圣君、明王、忠臣、烈士、强兵、勇將、孝子、顺孙等事，其他财物，如粪土耳。姑以尔境内眾所闻者明之：昔隋史萬歲守邊，夷而贪财，以致殺身。梁毗一金不受，而大服夷眾。此事甚白。吾为圣朝天使，必不为财物所蛊，惟恐吾之使令往来小人，不体吾意，蛊惑尔心，特此叮咛。尔其备审此书，体吾真意，早送吾辈還朝，則尔敬君之心，不浅浅也。』
|
|-
|书至，思侖發悦服，遂邀至其家，設宴畢，與其眾送出境外。
|
|-
|百夷，由金齒、蒲漂過怒江即其境。沿江東數十里，上有高良弓頗险。其岭有一寨。過一寨下四十里，地名养列，自此抵麓川無险隘之虞。由麓川经蠻牛、莽港等路，渡谨卯，從蒙戛等甸至麻林界，登金沙江之舟，下流二十日至緬國。國王眾呼为卜剌浪，王之妻呼为米泼剌。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>6eulnpvzksi6fpiv4f3h1rytnfka09x</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:~2026-49632-08</title>
    <ns>3</ns>
    <id>485572</id>
    <revision>
      <id>4669805</id>
      <timestamp>2026-09-13T04:08:02Z</timestamp>
      <contributor>
        <username>MathXplore</username>
        <id>3097823</id>
      </contributor>
      <comment>Notifying author of speedy deletion nomination</comment>
      <origin>4669805</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="935" sha1="b4j6yy8f4ykbu7l8658aauvuf8wr9di" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Talk:Introduction to Computer Information Systems/Print version]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Introduction to Computer Information Systems/Print version|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 04:08, 13 September 2026 (UTC)</text>
      <sha1>b4j6yy8f4ykbu7l8658aauvuf8wr9di</sha1>
    </revision>
  </page>
  <page>
    <title>User talk:~2026-49447-94</title>
    <ns>3</ns>
    <id>485576</id>
    <revision>
      <id>4669838</id>
      <timestamp>2026-09-13T07:13:05Z</timestamp>
      <contributor>
        <username>MathXplore</username>
        <id>3097823</id>
      </contributor>
      <comment>Notifying author of speedy deletion nomination</comment>
      <origin>4669838</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="846" sha1="gfu5pp9f1cu3xa3uek55hjynjpmdxgg" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Wii Fit/Free Run]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Wii Fit/Free Run|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)</text>
      <sha1>gfu5pp9f1cu3xa3uek55hjynjpmdxgg</sha1>
    </revision>
    <revision>
      <id>4669840</id>
      <parentid>4669838</parentid>
      <timestamp>2026-09-13T07:13:24Z</timestamp>
      <contributor>
        <username>MathXplore</username>
        <id>3097823</id>
      </contributor>
      <comment>Notifying author of speedy deletion nomination</comment>
      <origin>4669840</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="1704" sha1="fmugovevqueaqpcqvge3k8xdnwdavca" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Wii Fit/Free Run]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Wii Fit/Free Run|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Definition of popsicle]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Definition of popsicle|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)</text>
      <sha1>fmugovevqueaqpcqvge3k8xdnwdavca</sha1>
    </revision>
    <revision>
      <id>4669842</id>
      <parentid>4669840</parentid>
      <timestamp>2026-09-13T07:13:51Z</timestamp>
      <contributor>
        <username>MathXplore</username>
        <id>3097823</id>
      </contributor>
      <comment>Notifying author of speedy deletion nomination</comment>
      <origin>4669842</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="2616" sha1="0kkc2cvy3np31vecbyhbtgk9easjnlc" xml:space="preserve">
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Wii Fit/Free Run]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Wii Fit/Free Run|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Definition of popsicle]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Definition of popsicle|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)
== I have added a tag to a page you created ==
Hi! I'm MathXplore, and I recently reviewed your page, [[:Binary Logarithm Relative Table: Mersenne Factors]]. I have added a tag to the page, because it &lt;strong&gt;may meet the [[Wikibooks:Deletion policy#Speedy deletions|criteria for speedy deletion]].&lt;/strong&gt; This means that it can be deleted at any time.  If you believe that your page should not be deleted, please post a message on [[Talk:Binary Logarithm Relative Table: Mersenne Factors|the page's talk page]] explaining why. &lt;strong&gt;If your reasoning is convincing, your page may be saved.&lt;/strong&gt; If you have any questions or concerns, please [[User talk:MathXplore|let me know]]. Thank you! &lt;!-- Substituted from User:JJPMaster/CurateThisPage/authorMsg --&gt; [[User:MathXplore|MathXplore]] ([[User talk:MathXplore|discuss]] • [[Special:Contributions/MathXplore|contribs]]) 07:13, 13 September 2026 (UTC)</text>
      <sha1>0kkc2cvy3np31vecbyhbtgk9easjnlc</sha1>
    </revision>
  </page>
  <page>
    <title>User:Taitesena/Unofficial History of Nanzhao</title>
    <ns>2</ns>
    <id>485577</id>
    <revision>
      <id>4669882</id>
      <timestamp>2026-09-13T10:54:25Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>Created page with &quot;__NOTOC__ {{incomplete translation}} {{Translation header  | title    = Unofficial History of Nanzhao (南诏野史)  | author   = Yang Shen (杨慎)  | override_editor   =   | translator = 'Taitesena'  | section  =  | previous =  | next     =  | shortcut =   | year     =   | language = zh  | original =   | notes    =    }}  == Front Matter ==  # [[Unofficial History of Nanzhao/Translator's Note|Translator's Note]] # Unofficial History of Nanzhao/Influences|Historical...&quot;</comment>
      <origin>4669882</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="47885" sha1="eecqacp2ieunnnjs4cz4yibescihvq7" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Unofficial History of Nanzhao (南诏野史)
 | author   = Yang Shen (杨慎)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    =   
}}

== Front Matter ==

# [[Unofficial History of Nanzhao/Translator's Note|Translator's Note]]
# [[Unofficial History of Nanzhao/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Authorship 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|增订南诏野史上卷 明 四川新都杨愼升庵编辑
|
|-
|}

===The Title of Nanzhao 《南诏之称===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Title of Nanzhao 《南诏之称》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|蛮夷称王曰诏。先时滇有六诏，各据其地。六诏中蒙舍诏最强，后并吞五诏，故独称南诏。
|
|-
|六诏考六诏之地，东西四千里，南北二千九百里
|
|-
|蒙舍诏蒙细奴逻立国，居蒙舍川，地在永昌、姚州之间，处五诏之南。后奴逻曾孙皮逻阁并吞五诏，独称南诏。今蒙化厅是邆赕诏丰咩立国，居邓川。今大理府邓川州是施浪诏施望欠立国。居{{浪穹弥茨河蒙次和山，今大理府浪穹县是浪穹诏丰时立国，居浪穹。后其孙铎罗望迁剑川，改称剑浪诏。今丽江府属剑川州地是越析诏波冲立国。亦称摩诏。又号花马国。居嶲州。今丽江府是后，其兄之子于赠渡泸，邑于龙佉河蒙嶲诏嶲辅立国。居越嶲，今四川宁远府，越嶲厅是
|
|-
|}

===The Territorial Divisions of Nanzhao 《南诏分野》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Territorial Divisions of Nanzhao 《南诏分野》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|在天井鬼入参一度，汉书。次鹑首末位晋书。丽中台上位北斗开阳一星。宋书。在地乃梁州裔土，蜀之苑囿。河图纬。
|
|-
|}

===The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周鄯阐国、白崖国、昆弥国。战国时滇国，汉西南夷、益州、白子国。后汉建宁国。晋、宋、齐、梁、陈，宁州。隋昆州。唐初，南宁、六诏，唐文宗太和间，名鄯阐府。宋仍名南诏。元名中庆。明名云南省。
|
|-
|	国朝因之。按：汉武帝元狩元年，彩云见南中，在今大理府赵州之白崖。云南之名始此。唐元宗间问蒙舍诏盛逻皮之相张建一作俭成住何处？曰：「南边云下。」因命为云南。又元宗见祥云起，名祥州。今大理府之云南县也。
|
|-
|}

=== General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|鄯阐国蒙苴颂，昆弥国庄蹻、仁果、龙佑那据于周、秦、汉迄六朝。细奴逻据于唐。郑买嗣、赵善政、杨于贞、段思平、高升泰曁正湻，相继据于唐末迄
南宋。凡历有九姓，而雍闓、孟获不与焉。段氏与南宋理宗壬子湻佑十三年为蒙古所灭，而段实于理宗景定二年袭总管，传十二世，明太祖壬戌洪武十五年平云南，擒段世，并段段明之二子苴仁、苴义。赐苴仁官雁门卫镇抚，苴义官武昌卫镇抚，段氏之世土方绝，而又别封其族人段保为大理府云龙州土知州。国朝尚有袭土职者。
|
|-
|}

=== Titles and Official System of Nanzhao《南诏称谓官制》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Titles and Official System of Nanzhao《南诏称谓官制》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|南诏称帝曰骠信，王曰诏，自称曰元，称后曰信么，亦曰九么，妃曰进武，兄曰容，弟曰钟，下曰昶。其设官则有把国事八人，曰坦绰，曰布燮，曰九赞，谓之清平官。曰酋望，曰正酋望，曰员外酋望，曰大（将军）〔军将〕，曰员外。又设九爽之名，爽，省也。功爽主官人，宗爽主户籍，万爽主财用，慈爽主礼，引爽主宾客，幕爽主兵，罚爽主刑，厥爽主工作，禾爽主商贾，皆清平官、酋望、大军将兼之。以清平官子弟为羽仪长八人，清平官见王不得佩剑，惟羽仪长佩之。又有六曹长二人，曹长有功升大军将，凡十二人。又立三托：巨托主仓廪，气托主马，禄托主牛。大府主将曰演习，副曰演览；中府主将曰缮裔，副曰缮览；下府主将曰澹酋，副曰澹览；小府王将日幕撝，副曰幕览。每府有陀酋，陀酋卽掌书记判官之类。外有八节度使：日弄栋节度使，今楚雄府姚州。曰银生节度使，今景东厅及鎭沅州地是。曰永昌节度使，今永昌府是。曰丽水节度使，今丽江府是。曰剑川节度使，今丽江府剑川州是。曰东川节度使，今东川府府是。曰通海节度使，今临安府通海县是。曰拓东节度使。今云南府昆阳州北平定乡，蒙氏子凤伽异曾筑城于此地。又有二都督：曰会川都督，今四川宁远府会理州地是。曰通海都督。又设十睑，蛮语谓州为睑。苴音斜。羊睑，又名羊睑，卽今大理府太和县。赵州睑，今大理府赵州。白崖睑，又名勃弄睑，今赵州之白崖。，云南睑，今大理府云南县。蒙舍睑，今蒙化厅。大厘睑，又名史睑，今太和县喜州。邆川睑，今大理府邓川州。品澹睑，蒙秦睑，矣和睑。三睑未详其地。○蔚按：别本十睑中苴羊睑、赵州睑、白崖睑而下，作义督睑，今剑川州；威远睑，今普洱府威远厅南；河东睑，末详其地；越睑，今永昌府腾越州；北方睑，又名成偈睑，今永北厅；楼头睑，今四川叙永厅，属永宁县；路睑，今楚雄府广通县；与云南睑以下七睑异。○按：又考此七睑中，其越睑、北方睑、楼头睑、路睑凡四睑，见于『汉地里志』及『唐书?南蛮传』中，睑并作赕，音闪，字旣不同，音又各异，似非列于十睑之数。凡人丁壮者皆为战卒。王之亲兵曰朱弩佉苴，音蛆。按：元微之白乐天乐府皆作佉嗟，未审孰是。佉苴，韦带也。每兵百人置罗苴子统一人，戴朱鞮鍪，负犀革铜盾而跣足。自大军将以至曹长，皆系金佉苴尚绛紫，有功加锦，又有功加金波罗。卽虎皮。民兵号白衣，凡民兵出以望苴蛮为先驱。
|
|-
|}

===Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|因远部。威远睑治，其地总名和泥，今元江府是。休腊部。今临安府河西县。嶍峨部。今临安府嶍峨县。屈中部。今临安府阿迷州。溪处甸部、伴溪落恐部。今倶为长官司，属临安府。铁容甸部。今为亏容长官司。官桂思陀部。今为思陀甸长官司，皆属临安府。王弄部、强现三部。今属开化府。师宗部。今广西州师安县。弥勒部。今广西州弥勒县。吉输部、袖恶部。倶在弥勒县地。维摩部。卽广西府维摩州。州裁，今属广西州地。罗雄部。今曲靖府罗平州。纳垢州。今曲靖府马龙州。落温部。今曲靖府陆凉州。磨弥部。今曲靖府沾益州。仁德部。今曲靖府寻甸州。夜苴部卽曲靖府亦佐县，县裁，今归罗平州。强宗部。卽澄江府阳宗县，县裁，今归河阳县。步雄部。今澄江府江川县。罗伽部。卽步雄部分地。休制部。今澄江府新兴州。落蒙州。今澄江府路南州。弥沙部、邑市部。皆落蒙部子孙分治之。阳城堡部。今云南府晋宁州。罗部。今云南府罗次县。乾矢部、罗婺部。倶在武定府曲州，州裁，今属武定州。华竹部。今武定州元谋县。洪农碌券部。今武定州禄劝县。掌鸠法块部在禄劝县城东五里。○以上三十五部在迤东地。白鹿部。今楚雄府。谋统部。今丽江府鹤庆州。○以上二部在迤西地。
|
|-
|}

==Nanzhao through the Generations《南诏历代》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Nanzhao through the Generations《南诏历代》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|白古记：西天天竺摩竭国阿育王骠苴音斜。低娶欠蒙亏为妻，生低蒙苴。苴生九子，长子蒙苴，附罗十六国之祖；次子蒙苴廉，吐蕃之祖；三子蒙苴诺，汉人之祖；四子蒙苴酬，东蛮之祖；五子蒙苴笃，生十二子，七圣五贤，蒙氏之祖；六子蒙苴托，狮子国之祖；七子蒙苴林，交趾国之祖；八子蒙苴颂，白子国仁果之祖；九子蒙苴閦初六切。白夷之祖。○『哀牢今永昌府。夷传』：哀牢蛮蒙伽独捕鱼易罗池在永昌府城南。溺死。其妻沙壹一作壶。往哭之水边，触一浮木，有感而妊，产十子。后携子至池上，木化为龙，人言曰：「我子安在？」九子惊走，独季子背龙而坐，龙舐其背。蛮语谓背为九，坐为隆，故名之曰九隆氏。哀牢山一名天井山，在永昌府。下有妇名奴波息，生十女，九隆弟兄娶之，立为十姓：董、洪、段、施、何、王、张、杨、李、赵，皆刻画其身象龙文，于衣后著尾。子孙繁衍，居九龙山山在永昌府城南。溪谷间，分九十九部，而南诏出焉。
|
|-
|}

===Shanchan Guo《鄯阐国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shanchan Guo《鄯阐国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周时立国，年代久远，其姓名世次莫考。
|
|-
|}

===Baiya Guo《白崖国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baiya Guo《白崖国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|西天天竺摩竭国阿育王低蒙苴第八子，蒙苴颂居白崖，因地名，号白崖国，传世莫考。后昆弥氏继之，号昆弥国。
|
|-
|昆弥国一名拜国。
|
|-
|昆弥氏，传世姓名莫考。战国时，楚将庄蹻据滇，并有其地，号滇国。
|
|-
|}

===Dian Guo《滇国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dian Guo《滇国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|战国时，楚顷襄王命将庄蹻范蔚宗后汉书作庄豪。将兵循江上，略巴、蜀、黔中以西，蹻至以兵威畧定滇地属楚。欲归报，会秦司马错攻楚，黔中道塞。蹻遂以其众王滇，号滇国，踞之。后有王常羌者好佛，国势不振。法令不行，国人遂推白崖国蒙苴颂之后，白饭王之裔仁果为王，治白崖，于是两国角立。后仁果奉汉，封为白子国。
|
|-
|}

===Baizi Guo《白子国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baizi Guo《白子国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|汉武帝通西南夷，遣使至滇，求身毒国。滇王常羌问使者曰：「汉孰与我大？」使者还报，武帝怒其言不逊。时白崖国蒙苴颂之后，天竺国白饭王之裔仁果者，为众所推立于白崖。武帝乃册封仁果为王，号白子国。后迁于澄江，今澄江府。迨龙佑那继之，号建宁国。○又一说：白子国之先，有阿育国，王能乘云，上天娶天女，生三子，长季二子封于金马、碧鸡，独封仲子于苍洱之间，崇奉佛敎，不茹晕，日食白饭，人因称为白饭王。迨后有仁果者，汉封为滇王，号白子国。又十五世至龙佑那，后汉诸葛武侯南征，次白崖，以佑那为酋长，赐姓张氏，仍统其民，号建宁国。
|
|-
|}

===Jianning Guo《建宁国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|后汉后皇帝乙巳建兴三年，益州耆帅雍闓，假鬼术杀建宁太守王昂，归东吴，吴王孙权以闓为永昌守。后汉诸葛武侯南征，至白崖，杀雍闓，擒孟获，乃封白子国王仁果十五世孙龙佑那为酋长，赐姓张氏，于白崖筑建宁城，蔚按建宁城废址在今大理府赵州之弥渡。号建宁国，立铁柱蔚按：今弥渡有铁柱宫，铁柱尚存。先为建宁国王张乐进求甫铸，后南诏蒙世隆复重铸，名曰天尊柱，高八尺。并『南中纪功碑』，铭其背曰：「万岁之后胜我者过此」。迨至隋时，行军总管太平公史万岁征南宁夷爨玩，西破三十馀部，至此，见其碑铭，命左右踣之。其碑跌，中复有志曰：「史万岁不应踣吾碑」。万岁惊异，复树碑，祭拜而去。后张龙佑那仍迁国澄江，传三十二世至十七世孙张乐进求，唐太宗己酉贞观二十三年封为首领大将军。后见蒙舍川蒙细奴罗有奇相，遂妻以女，逊国与之。奴罗自称奇嘉王，建号大蒙国，又称南诏。
|
|-
|}

==Nanzhao《南诏国》==
===13 Generations of Nanzhao 《南诏大蒙国传十三世》 ===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ 13 Generations of Nanzhao 《南诏大蒙国传十三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|细奴一作农。逻一作罗。　伪谥高祖奇嘉王
|
|-
|细奴逻，又名独罗消，西天天竺摩竭国阿育王低蒙苴第五子蒙苴笃之三十六世孙。生有奇相。唐太宗贞观初，其父舍龙尨，又名龙伽独，将奴逻自哀牢避难至蒙舍川，耕于巍山。今蒙化厅之巍宝山。一日，有老僧，美髯，冠赤莲冠，披袈裟，持钵至奴逻家乞食。时奴逻与子逻盛炎方耕巍山之下，其姑与妇将往饁。见僧乞食，遂食之。再炊往饁，僧坐不去。姑妇持饷中道，僧已在彼，复乞食，姑妇又食之。返而复炊，持饁至巍山，则见僧坐盘石上，前有靑牛，左白象，右白马，上覆云气。云中二童子，一执铁杖于左，一执方金镜于右。姑妇惊喜，复以所饷供之。僧问何所愿？姑妇不知对。僧曰：「奕叶相承」。及趣奴逻等至，则但见一人持钵，坐五色云中，而盘石上惟馀衣痕及牛象马之迹耳。奴逻素有祥异，会唐封首领大将军建宁国王张乐进求，以诸葛武侯所立白崖铁柱，岁久剥蚀重铸之。因社会祭柱，柱顶故有金镂鸟，忽能飞，集奴逻左肩，相诫勿动，八日乃去。众骇异，谓天意有属。进求遂妻以女，举国逊之。于唐太宗己酉，贞观二十三年卽位，年三十二岁，建号大蒙国，称奇嘉王，据南诏。高宗庚戌永徽元年，建都蒙舍川，于巃｛山＋于｝山在今蒙化厅西北三十五里。筑巃山＋于城。永徽癸丑四年，遣逻盛炎入朝唐，诏授奴逻为巍州今蒙化厅刺史，赐以锦袍。大勃弄今大理府赵州白崖。酋杨承顚寇麻州，在今曲靖府马龙州城北里许。唐命郞州唐贞观初，分牂牁郡北界置郞州，后改名播州，卽今贵州遵义府。又有郞州，在今云南县地。道行军总管赵孝祖讨之。孝祖先入小勃弄，今云南县地。酋长没盛迎战，孝祖斩之。进至大勃弄，攻其城，破之，擒杨承顚，改云南县为匡州，领勃弄、匡州二县。高宗显庆二年，凤鸣于浪穹罗浮山，乃改名为凤羽山，在大理府浪穹县西南三十里，又名鸟吊山。见『水经注』。封十二圣贤为十二山神。时澄江人波罗旁有经济才，用为文臣；郭郡矣素以勇略闻，用为武臣。又有杨波远者，相传为东汉时人，常骑三角靑牛，号神明大士，能知盐泉，滇中盐泉多为波远所开创。奴逻在位，遵唐正朔。高宗甲戌上元元年，奴逻卒，在位二十六年，子逻盛炎立。
|
|-
|逻盛炎又名逻晟。伪谥世宗兴宗王。
|
|-
|	逻盛炎。唐高宗甲戌上元元年卽位，年四十岁，以张建成为相。明年，盛炎临朝，元宗壬子先天元年，姚州蛮叛归吐蕃。唐命御史李知古讨之，筑城立州县。知古诛豪杰，掠子女，蛮怨，引土蕃，攻杀知古，于姚嶲路绝，而盛炎独奉唐正朔。是年，盛炎卒，在位三十九年，子盛逻皮立。
|
|-
|}


===Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|盛逻皮，唐元宗壬子先天元年卽位，年四十岁。明年为元宗癸丑开元元年，唐授逻皮为特进，封台登郡王今四川宁远府冕宁县地。设官征商税。开元二年，遣张建成入朝于唐。立土主庙。开元九年，皮叛唐。开元十四年，立庙祀晋右将军王羲之为圣人。元宗戊辰开元十六年，逻皮卒，在位十六年，子皮逻阁立。
|
|-
|皮逻一作罗阁石刻作归义王魁乐觉封云南王。
|
|-
|皮逻阁，唐元宗戊辰开元十六年卽位，年三十一岁。开元十八年，灭五诏，自称南诏王。先是，蒙氏恐三十七蛮部不服，选亲族为五诏。未几五诏抗命，逻阁遂赂剑南节度使王昱，求合六诏为一。昱奏于朝，许之。逻阁乃豫建松明大楼，祀祖于上。使人谕五诏曰：「六月二十四日乃星回节蔚按『大理郡志』汉元封间，叶楡妇阿南者为酋长，曼阿娜之妻。娜为汉将郭世忠所杀，欲妻南。南曰：能从三事，当许汝一作幕次祭故夫；一焚故夫衣，易君新衣；一令国人皆知我以礼嫁。忠如其言。明日，聚国人张松幕祭其夫。下置火，南藏刃出，俟火炽焚夫衣，卽引刀刃自断其颈，仆火中，时六月二十五日也。国人哀之，故岁以是日燃炬吊之，名为星回节云。是又当为二十五日。当祭祖，不赴者罪。」四诏听命。惟越析诏波冲之兄子于赠，远不赴会，而邆赕诏丰哶孙｛辵＋皮｝逻邆之妻慈善者，止逻邆勿赴。邆不听。慈善不得已，以铁钏穿于邆臂而行。二十四日，逻邆及施浪诏施望欠弟施望千、浪穹诏丰时孙锋罗望、蒙嶲诏嶲辅子罗原皆至逻阁所。逻阁偕登楼祭祖，祭后享胙食生饮酒，迨晚，四诏尽醉。逻阁独下楼，焚钱遽纵火，火发，兵围之，四诏皆焚死。逻阁遣使至四诏所，报焚钱失火，四诏被焚，状令各诏收骨。四诏妻至，莫辨其骨。独慈善因铁钏得焉，携归葬之。逻阁旣灭四诏，取各诏宫人，念慈善慧而甚美，遣兵围其城，迫取之。慈善曰：「吾岂忘夫事仇者？」闭城坚守，半月城中食尽，慈善度不能支，卽自杀，时七月二十三日也。逻阁嘉其节，乃封赠为宁北妃，并旌其城曰德源城。城废址在今大理府邓川州城东北二里许。开元戊寅二十六年，逻阁破吐蕃及弥蛮，入朝，元宗礼之，加封为特进，云南王，越国公，开府仪同三司，赐名归义，并锦袍金钿带七事。王归国，以兵逐洱河蛮，筑太和城，今大理府城南十五里太和村地是。又筑大厘城今大理府城北四十里喜州是。守之，尽有云南之地。唐授王子阁逻凤右领军卫大将军兼阳瓜州刺史。开元二十七年，明矫叛，破剑川、浪穹、永昌。开元二十八年，王讨朋矫，平之。开元辛已二十九年，王自蒙舍川迁居太和城，立龙首、卽今上关。龙尾卽今下关。二关。唐加阁逻凤为左领军卫大将军。元宗癸未天宝二年，筑羊苴哶城于太和城之北。卽今大理府城。唐迁阁逻凤为左金吾卫大将军，寻拜特进都知兵马大将军。天宝甲申三载，西方进狮子皮。唐加阁逻凤为上柱国。天宝乙酉四载十月，城永昌。天宝丙戌五载，王遣孙凤伽异入唐，唐授伽异为鸿胪少卿，妻以宗室女，赐龟兹乐一部，元宗戊子天宝七载，王卒，在位二十年，子阁逻凤立。
|
|-
|阁罗凤一作觉乐凤。按：『德化碑』云：「家居阁罗凤」，则是取地名以为名也。袭封云南王，伪谥神武王。始建元。
|
|-
|	

阁罗凤，唐元宗天宝戊子七载卽位，年三十六岁。唐遣中使黎敬义持节册凤袭封云南王，敕置阳瓜州于蒙舍川，加授

凤伽异为上卿兼阳瓜州刺史，都知兵马大将军。天宝庚寅九载，王率妻子往谒都督李宓，过云南，太守张虔陀私之，又多徵求。王表虔陀之罪，中官贾奇俊抑之，不得达。王复遣将军杨罗顚等连表控告。元宗仍不省。凤怒，遣大将军王毗双、罗时等发兵攻虔陀。虔陀饮鸩死；遂取姚州，并夷州三十二。获唐嶲州西泸令郑回以归，爱其才，用为清平官。天宝辛卯十载，唐命剑南节度使鲜于仲通将兵八万征云南。凤赴泸南在楚雄府姚州之城北一百五十里。谢罪，愿还所俘掠，请罢兵。仲通不许，分三道而进。仲通自南溪路，大将李晖自会同路，都督王知进自步头路。今临安府地。凤就安宁，再伸衷悃。仲通不听，兵至曲州、靖州。二州今为曲靖府地。凤复遣首领杨子芬、参军江如之赍状，言若不罢兵，卽当归吐蕃，恐云南非唐有。仲通终不许，囚其使，进薄白崖城。别遣大将王天运统师绕出点苍山后。凤遣

凤伽异及大军将段俭魏迎山后师，自逆战于西洱河。唐兵大败，死者六万人，王天运战殁，仲通仅以身免。凤乃叛唐，建元长寿。遣弟阁陂和尚及子铎传、酋望赵佺邓、杨传磨侔等，并子弟六十人献凯吐蕃。陂有神术，人马往来吐蕃，不过朝夕之顷。天宝十一载正月一日，遣宰相倚祥叶乐持金冠、锦袍、金宝带、金帐状、安扛伞鞍、银兽器皿、珂贝、珠毯、衣服、駞马、牛鞻等物至邓川，以凤为兄弟之国，册为赞普钟南国大诏，给金印，称东帝。并授凤伽异大瑟瑟告身，都知兵马大将。凤遂改是年为赞普钟元年。发人口百户于浪穹，筑白崖睑城，又遣兵攻掠安宁。天宝甲午十三载六月，唐命前云南郡都督兼侍御史剑南留后李宓、广府节度使何履光等，率十道兵再征云南。兵逼邓川，凤遣凤伽异、段俭魏迎战于江口。时神川都知兵马使论绮里徐救兵已至巴蹻山，遂诱宓深入，内外夹击。宓粮尽，士卒饥疲，引还。凤以精兵追战，唐全军覆没，李宓被执，沉江死，何履光遁去。凤因进取嶲州会同郡，据清溪关，以破越析。此二役也，皆凤弟阁陂和尚及凤妃白氏行妖术，展帕拍手而笑，韩陀僧用钵法，以故唐兵再败。时唐先后丧师已二十馀万，凤乃敛战胔，筑京观于龙尾关河尾，名万人冢，立碑大书「唐天宝战亡士卒之墓」。而唐宰相杨国忠更揜败以捷闻，叙战功。令清平官郑回撰『德化碑』，唐流寓御史杜光庭书。立石太和国门外，明其不得已叛唐归吐蕃之故。天宝乙未十四载冬十一月，东平郡王安禄山反于范阳，凤乘机以兵取蜀卭州，筑卭子城，及丽水金宝城。升段俭魏为清平官，赐名忠国，旋拜相国。代宗甲辰广德二年，羊苴哶城成，凤名之曰大理城，又名紫城。代宗乙巳永泰元年凤伽异筑云南城卽今云南府省城。又筑拓东城，今云南府昆阳州北平定乡。遂以兵攻陷曲靖。代宗丁已大历十二年，永昌牛生三角，羊生四角，鸡九足，井有光。建观音寺于白崖。先是，逻盛炎时，相国张建成欲于白崖建寺，卜之吉。又地下有三戳观音，上截在西，中截在东，下截在东南。因盛炎旋卒，不果建。至是建寺，掘之果然。代宗戊午大历十三年，阁罗凤卒，在位三十年。因子凤伽异先死，后追谥悼惠王。孙异牟寻立。
|
|-
|异牟寻改国号曰大理国。封云南王，又封南诏王　伪赠廪孝桓王
|
|-
|异牟寻，唐代宗戊午大历十三年卽位，年二十四岁。明年改元见龙，又改上元，率兵三万取蜀为东府，又连土番入寇。唐命神策都将李晟击破之。师还，自称南诏王。德宗甲子兴元元年，牟寻迁居史城，卽大厘城。改号大理国，自称日东王。封岳读，以叶楡今大理府。点苍山为中岳，乌蛮今东川府。乌龙山一名绛云弄山，在今禄劝县东北三百里。为东岳，银生府今景东厅。蒙乐山一名无量山，在厅北九十里。为南岳，又封南安州今楚雄府属。神石亦为南岳，越赕今永昌府腾越州。高黎贡山一名昆仑隅，在腾越、潞江之间。为西岳，嶲州今丽江府是。雪山一名玉龙山，在府西北二十里。为北岳。封金沙江源出吐蓄旄牛徼外犂牛石下，本名犂牛河，又名犂水，讹为丽水。经丽江府、鹤庆州、姚州而东北达于四川马湖府之马湖，卽『山海经』所谓若水。『水经注』云：若水经云南之遂久县，卽今金沙江巡检司地。昔黄帝长子昌意德劣，不足绍承天位，降居斯水为诸侯，娶蜀山氏女，生颛顼于若水之阳，疑卽其地也。祀在武定州，兰沧江源出吐蕃鹿石山下，本名鹿沧，又名兰沧。兰沧讹为浪沧。自丽江府度云龙州至永昌府，东经顺宁府，达于车里，过交趾地而入于南海。祀在丽江府，黑惠江在顺宁府之东入狼沧江，而达于南海。祀在顺宁府，怒江源出西域雍望，奔流而下，深不可测。夏月多瘴，经怒夷地入丽江府境野人界。至永昌府境，乃名潞江。祀在水昌府，为四渎，各建神祠。又立三皇庙。德宗丙寅贞元二年，设官立九爽三托。考疆域，其地东至于铜柱、铁桥、蟠桃、玉楡，东南至于交趾国，南至于骠国，西南至于木落山，西至于太石，西北至于吐蕃，北至于神川，东北至于黔巫。八分之地，属以八演，皆中国降人为之经画者。贞元丁卯三年，寻居大理城。命子弟师事郑回。时寻苦吐蕃徵求无厌，会李泌劝德宗招云南以断吐蕃右臂。帝从之，命韦皋为西川节度使，皋受命招抚群蛮。郑回因说寻归唐，寻以为然。皋遣谍者致书于寻，吐蕃知而疑之，乃责南诏大臣为质。寻愈怨。于是，决计归唐。皋以闻，德宗乃命皋作书谕寻。是年四月，吐番破蜀，来征兵，蔚按：卽吐蕃劫浑瑊清水盟之岁。寻谢绝之。贞元五年，寻遣乌蛮勿邓大鬼主苴梦冲、两林都大鬼主直那时聘于皋，因入朝。皋遣其属崔佐时报之。时吐蕃使数十人先在，佐时至，寻令更衣入。佐时不可，曰：「天朝大使。岂衣夷衣？」寻不得已，夜迎之。佐时至，大宣诏旨，令寻斩番使，去其所立之号。寻遂与佐时盟于点苍山下。贞元九年，寻遣使上表，请从韦皋袭吐蕃。诏册封为云南王，以韦皋为云南安抚使。王遣使诣皋，献夷中歌。贞元十年，吐蕃徵兵于王，王阳示寡弱，以兵三千应之，自将数万人踵其后。正月，袭吐蕃，战于神州，断铁桥，在巨津废州，今丽江府西北地。取十六城，俘其五王，降众十馀万，获军资甲仗无算。遂遣弟凑罗栋、清平官尹仇宽献捷于唐，并献地图、纳贡及吐蕃所给金印，请复号南诏。于是，唐以祠部郞中袁滋为中丞，赐金紫充册使。赐王银窠金印，印文曰：「贞元册南诏印」。王北面跪受。宴使者，出元宗天宝五载所赐王父凤伽异银跳脱马头盘数物，并指老笛工、歌女曰：「皇帝所赐龟兹乐，惟二人在耳！」使者日：「南诏世荷唐恩，当深思祖考子孙勿替，尽忠皇唐。」王对曰：「敢不敬使者之命。」随遣清平官尹辅首入谢，献铎鞘、郁刀、生金、瑟瑟、牛黄、氎、纺丝、越赕绕伦马。蔚按：铎鞘，疑当作择矟，状如残月，有孔旁达，出丽水，饰以金，月祭之血，所击无不洞。段柯古『酉阳杂俎』云：南蛮有毒槊无刀刃，状如朽铁，中人无血立死。言自天而下，入地丈馀，祭地乃掘得之，云云。疑卽铎矟，毒为铎字之讹，槊字本同矟宇也。郁刀铸时以毒药并冶，取莹耀如星者，凡十年乃成，淬以马血，镂金犀饰镡首，伤人卽死。因浪人所铸，又名浪剑，夷中甚宝之。七月，又攻吐蕃，并破施蛮、顺蛮，施蛮、顺蛮卽施浪、浪穹二诏之后，自南诏并吞五诏，五诏之后不复称诏，止称蛮。俘其王置白崖城。贞元十二年，取越赕，置软化城。贞元十四年，请以大臣子弟质于朝，韦皋却之。固请，乃尽舍成都，遣就学。贞元十五年，王开白国北方赕地，今永北厅。徙弥河白蛮及罗落摩蛮实之，号剑羌。是年，王从韦皋再败吐蕃于铁桥。初，王谋击吐蕃，以邆川、卽今邓川州。宁北卽今浪穹县。等城当寇冲，乃峭山深堑，修战备。至是吐蕃谋袭南诏，王告于皋，遣将屯黎州、嶲州以应之。吐蕃引兵攻嶲州，皋严兵以守，别遣将袭击，降其帅，吐蕃惧，退至铁桥。王令人毒其水，吐蕃人马多死，退屯三泸水，王与皋部将杜毗罗击败之。贞元十六年，王率子寻阁劝入朝于唐，召对延英殿，进奉圣乐舞，德宗御麟德殿观之。贞元十七年，王夜绝泸水，斩吐蕃屯卒，又合鬼主破之于泸西。吐蕃大惧，欲悉师收嶲州，以绝南诏。王谓韦皋曰：「吐蕃声取嶲州，实窥云南，请进军羊苴咩城。」皋督诸将分道与王会，陈兵深入，拔木波城。前后凡克城七，焚堡百五十所，斩获无算，生擒论莽热，献于唐，并进铠甲十五万。皋班师，帝遣中使慰抚王。王自是比年贡方物，唐帝深礼之焉。贞元十九年，王封云南金马碧鸡二山之神为景帝，建妙音寺塔，筑大理雪峰长城。宪宗戊子元和三年七月，王卒。唐遣使祭吊，在位三十年，子寻阁劝立。
|
|-
|寻阁一作觉劝又名新觉劝。　袭封南诏王　伪谥孝惠王
|
|-
|寻阁劝，唐宪宗戊子元和三年卽位，年三十一岁。唐册劝袭封南诏王，赐元和金印。宪宗己丑元和四年正月，改元应道，群臣上尊号曰骠信，以鄯阐为东京，大理为西京，重修曲靖崇真寺。寺为晋代所建。十一月王卒，在位一年。子劝龙晟立。
|
|-
|}

===Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝龙晟，唐宪宗己丑元和四年卽位，年十二岁。唐册袭封南诏王。明年，改元龙兴。铸佛三尊，送佛顶峰寺，用金三千两。元和九年，晨寇嘉定州，有飞天神兵破之。先是，节度使杜元颖守成都时，时滇兵至嘉定之沐源州，忽自惊溃。蜀军获一夷卒问之，云适见遍山神兵，一神将长斧坐二鬼上，声若迅雷，故尔惊走。至是神复现形，自后追杀，卽时死酋长二人。盖嘉定向有飞天神庙，两破滇兵者，皆此神也。宪宗丙申元和十一年，晟淫虐失道，弄栋节度使王嵯巅弑之，时年仅十九岁，唐命少监李铣祭吊，在位七年，弟劝利立。
|
|-
|}

===Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝利，唐宪宗丙申元和十一年卽位，年十五岁。唐册袭封南诏王。王嵯巅东寇。明年，改元全义。元和十三年，厚赏王嵯巅，赐姓蒙，封太容。元和十四年，废王嵯巅，赦其罪，命敬信三宝，为清平官。元和十五年，又改元大丰。重修崇圣寺。五月，大雨霖，龙首、龙尾二关倾。除洱河水怪，建龙屋塔。高十二丈。按：『白古记』：唐时洱河有妖蛇，名薄劫，兴大水淹城。蒙国王出示：有能灭之者，赏半官库，子孙世免差徭。部民有段赤城者愿灭蛇，缚刃人水，蛇吞之，人与蛇皆死，水患息。王令人剖蛇腹，取赤城骨葬之，建塔其上，毁蛇骨灰塔，名为灵塔。在今大理府城南龙尾关内点苍山马耳峰下羊皮村。每年有蛇党起风来剥塔灰。时有谣曰：赤城卖硬土。今『龙王庙碑』云：洱河龙王段赤城云。永昌生两头牛。穆宗甲辰长庆四年，赐南诏王金印。是年王卒于东京，在位八年，弟丰佑立。丰佑慕中国之风，独不肯连父名。丰佑石刻作劝丰佑　　册封滇王　　伪谥昭成王
|
|-
|	

丰佑，唐穆宗甲辰长庆四年卽位，年七岁。唐遣京兆少尹韦审规持节册封为滇王。王遣洪成酋等人谢。明年，改元保合，又改元天启。西僧赞陀啒哆建鹤庆元化寺。先是，鹤庆地水淹，僧杖刺东隅泄之。水中得樟木，刻为佛，咒之忽灵，远近名曰活佛。按：活佛，后至明成化间，福建莆田林俊为云南宪副闻之，亲至寺中，将佛火之，得金数百两入官，又毁他寺三百，人呼为林劈佛。建常平仓，筑邓川城。敬宗乙巳宝历元年，重修大理崇圣寺一名三塔寺。成先是，王嵯巅广寺基方七里。圣僧李成眉贤者建立三塔，高三十丈。佛一万一千四百，屋八百九十，铜四万五百九十筋。元和十五年经始，至是工竣。塔顶旧有铁柱款识云：「贞观六年尉迟敬德监造」，盖寺之建久矣。重修云南东寺塔，高百五十尺，西寺塔高八十尺，二寺亦贞观间将作大匠尉迟敬德所建。文宗丁未太和元年，王母出家，法名惠海。太和二年，用银五千，铸佛一堂，废道敎。太和己酉三年，僧梦岛造永昌卧佛，长丈六。六月朔，星落如雨。命王嵯巅等寇蜀。先是，西川节度使杜元颖失士卒心，军逃入南诏，因此知蜀虚实。佑遂遣嵯巅等攻蜀，陷嶲、戎、卭三州，攻成都，止西郛十日，掠经书、宝货、子女无算，蜀中残敝。并寇梓州、蜀州。佑上表于唐，请诛元颖。唐改云南为鄯阐府。卽今云南府省城。太和四年，唐贬杜元颖循州司马，以义成节度使李德裕为西川节度使。裕至西川，建筹边楼，日召习边事者访问，凡山川险要，南道与蛮相入者图之左，西道与吐蕃相接者图之右，不啻身尝经历焉。乃奏请留北兵以重镇守，修甲胄、备器械。率户二百取一人习战，作雄边子弟等十一军。筑仗义、御侮、柔远诸城以扼要害，复卭崃关，徙嶲州治台登，以夺蛮险。令转卭、雅粟以十月而运，先夏而至，人不苦瘴，边境始安。至是使人于佑，责归所俘。太和五年五月，佑归所俘西川四千人于德裕。太和六年，佑掠骠国民三千，徙之拓东城。武宗乙丑会昌元年，佑遣军将晟君筑横渠道自磨用江至于鹤拓，灌东皋及城阳田，与龙佉江合流入于河，谓之锦浪江。又潴点苍山玉局峰顶之南为池，谓之高河，又名冯河。更导山泉共泄流为川，灌田数万顷，民得耕种之利。会昌六年九月，佑攻陷安南，经略使裴元裕死之。宣宗丁卯大宗元年，佑妃卒，佑郁郁不乐，臣下请选妃女备后宫。得罗部今云南府罗次县。一美女进之，有宠。女好佛，建罗次寺，至今灵异。六月大旱，佑令僧寿海祈雨。僧曰：「昔汤旱七年，六事自责，天雨七日。今王酒色妄杀，天怒不雨。王如改悔，天雨自至，何以祈为？」佑如僧言，自责自改，数日果雨。佑女至崇圣寺进香，回至城西，为一乘白马人摄去，寻之不得。佑告于西僧赞陀啒哆，哆曰此山神也。乃设灯照之，果在苍山下。哆怒欲行法，移山于河。山神惧，献宝珠供佛，佑乃已。大中十二年，佑遣段酋迁陷安南都护府。遣段宗榜救缅。榜，汤今云南府宜良县地。人，佑之勇将。先是，狮子国侵缅；屡求救，至是许之。按：缅甸卽汉之掸国，唐之骠国，其历代莫考。当宋元之时，屡败王师。明太祖洪武十年，缅头目招扳南进贡。十九年，使行人司钱古训赍诏立宣尉司。二十年，缅犯景东。二十一年，犯他郞甸，沐英命都指挥宁正平之。三月，犯定边，沐英同都督冯诚平之。景泰三年，王骥赏缅孟养地。缅喜，乃擒献麓川贼。嘉靖初，缅火烧赍金牌官，中终年猖獗海上，遂至难制。○考自永昌府腾越州入缅，止三十四程。腾越一日南甸、一日罗必斯、一日郞、一日甸头、一日甸尾、一日蒙腰、一日甸蓝、一日蒙怜路、一日空地、一日蒙来路、一日大市、一日龙江、一日锅地、一日人列渡、一日江头城、一日景怜、一日及、一日马来城、一日赖当、一日山头、一日甸头、一日阿只、一日吴细辰、一日折弓、一日阿越。由阿越下水，九日卽至缅城。其地有五大城，江头、太公二城之外，又有马来、安正国、蒲甘缅王三城。酋住金楼，民住竹楼。其下称酋为卜剌浪，称酋妻为米泼剌。酋出人乘轿，水有舟筏。官名有招孟、招彔、招刚三等。官无大小，倶金银花宝带。无弓箭。其水有金沙江，险恶，缅恃以为固。涸时，亦仅五里。俗敬佛，重罪对佛发誓，凭僧处断。○入缅又有三道：一由潞江西上；一由腾越七日至麓川；一由景东从木通甸至湾甸渡入芒市，十日至麓川。○此外从潞江上流蒙来渡至景乐沿河有小渡十馀处，皆可通。又有三道：一由天步马，一由湾甸，一由阿郊地界，皆可入缅。宣宗己卯大中十三年，陷播州。李德裕旣贬死，西川节度使所任皆非人，侥佯边功，发兵十万袭滇，自建昌入，佑命子世隆为坦绰，同王嵯巅迎战于古宗，今丽江府铁桥以北地。杀唐兵数万人，立铜柱于界上。世隆之母，佑妃也，出家号师摩矣。尝随佑至罗浮山白城，建一寺，南壁画一龙，是夜龙动，几损寺，妃乃复画一柱锁之，始定。按：妃本渔家女，喜浴。为妃后，仍常泛舟西洱河，屏人潜浴于水，感金龙与交，生世隆。隆七岁，拳握始开，有文在其掌曰：通番打汉。古宗之战，唐帝惧世隆为患，妻以宗室女，伺察其所为。女以世隆年庚潜送于帝。帝使太史推之，知其感龙精而生。是年，丰佑卒于东京，在位三十五年。子世隆立，以王嵯巅摄政。段宗榜救缅，回至腾越，闻佑卒，世隆立，嵯巅摄政，移书王嵯巅曰：「天启不幸，驾崩嗣幼，闻公摄政，国家之福。榜救缅以败狮子国。缅酬金佛，当得敬迎。奈中国无人，惟公望重。榜抵国门之日，烦亲迎佛，与国增光。」云云。嵯巅不知是谋，至日迎之。榜令巅拜佛，突斩之于佛前。讨其弑劝隆晟之罪也。榜熔佛得金数千两。时有缅人奉香火者在榜，默祝曰：「愿世代奉敬，今不如愿，惟愿世尊轮生，灭彼国祚。」后果生郑买嗣篡国，灭蒙氏。
|
|-
|世隆『唐书』作酋龙。　　伪谥景庄皇帝僭称帝始此，以后郑、赵、杨、段、高五姓之国咸效之。
|
|-
|世隆，唐宣宗己卯大中十三年卽位，年十六岁。明年，为懿宗庚辰咸通元年，改元建极。改西京曰中都，东京曰上都。先是，德宗贞元间，西川节度使韦皋开道通南诏，令岁入贡。异牟寻、寻阁劝二世事唐唯谨，迨劝龙晟及丰［佑］，又数数扰边，大为唐患。又以世隆之名犯太宗、元宗庙讳。唐不册封，隆益致怨望。至是自称皇帝，遣兵取乌蛮、僰、爨之地，置东川郡。前节度使杜悰变韦皋制度，侵扰蛮中。隆绝朝贡，寇播州。至是李福为节度使，隆遣清平官董成至成都，移书于福。成与福抗礼，福囚之。上闻，有诏释成，召至京师，见便殿，遣还。咸通二年，遣兵陷安南。左仆射同平章事杜悰言：「西川兵弱，南诏强盛，未可轻绝。宜遣使祭吊，谕令改名，行册礼。帝肯之。会隆复寇嶲州，遂止。咸通三年，隆亲寇蜀，取万寿寺石佛归。时高真寺僧崇模有神术，从征。军中乏粮，又値岁暮，士卒思归，僧咒沙成米，咒水成酒，士卒各醉饱。一日僧化蝶回国乱宫，世隆妻以书达隆。隆答曰：妖若再来，令宫人于其衣背绣蝶。后僧复至，宫人绣之。隆见僧衣有蝶，令斩之。刑七次，首不殊。僧自云：用茅锯之乃断。果然。人见僧魂化一黑鹏飞去，盖僧本高真寺鹏巢中所得之儿也。咸通四年，寇西川。咸通五年，陷安南、邕管。咸通六年，陷嶲州。咸通七年，复攻安南。岭南西道节度使高骈救之，隆兵大败，骈遂定安南。咸通十年，隆遣使杨酋庆等入朝，谢释董成之囚。归成都俘三千人。定边节度使李师望杀其使，隆怒，率众攻蜀，陷嘉州。咸通十一年正月，陷黎州，入卭徕关，围雅州，击卭州，遂进攻成都。次眉州，西川节度使卢耽畏众寡不敌，通使请降。继而唐遣东川节度使颜庆复、大将宋威等率兵来战。世隆败屯星宿山，宋威戍沱江。隆迎战于毗桥，不胜，趋沱江，中伏。城中又出突将，夜火隆营，夺升仙梁。隆大败，奔双流江，无梁以渡，乃伪请和，三日梁成而济。咸通辛卯十二年，立鄯阐王宫。咸通壬辰十三年，于白崖诸葛武侯所立铁柱之地，铸天尊柱，高八尺。蔚昔年曾至铁柱宫，其地界白崖、弥渡、蒙化三境之间。其柱刻字云：建极十三年岁次壬辰四月朔庚子十四日癸丑建立。咸通十四年，攻黔中。又寇西川，作浮梁济大渡河，防河兵马使黄景复伏兵，半渡击败之。会隆国中新兵继至，接战，景复败走。隆进兵陷黎州，入卭徕关。遂遣王保诚等四十人谩书诣剑南节度使牛丛，欲假道入朝，请憩蜀王故殿。丛囚其使三十八人，释酇咙及段酋迁二人还。隆乃退兵至新津而旋。僖宗乙未乾符二年，攻雅州。西川节度使高骈追至大渡河，大败之，俘酋长五十人，收复黎州、卭徕关，斩黄景复以狥。乾符三年，遣使诣高骈请和，不许，斩使者一人。隆怒，自是唐使至不拜，惟拜和尚。骈知之，乃遣僧景仙往谕公主事，隆乃下拜定盟。禧宗丁酉乾符四年二月，复寇蜀，高骈御退之。骈又结吐蓄尚延心嗢、末鲁褥月等为间，筑戎川州、马湖沭沐源川、大渡河三城，列屯拒险，料壮卒为平夷军。世隆气夺，因恚发疽，卒于越嶲景净寺，在位十八年，子隆舜立。
|
|-
|}

===Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆舜，唐僖宗丁酉乾符四年卽位，年十七岁。明年，改元贞明，又改元嵯耶、承知、大同，改国号曰大封民国。遣使于唐请和，诏许之。自劝龙晟至世隆以来，侵蜀伐安南，用兵五十馀年，帑藏不给，横敛于民，上下倶困。舜立，耽于酒色，委政臣下，故愿求和于唐，乃遣段宝诣岭南节度使辛谠，请修好。谠奏，许之，以息边患。乾符六年，遣使于唐求和亲，无表，只用牒，称弟不称臣。唐帝召百官议，礼部侍郞崔澹曰：「南诏无礼，恐贻后笑。」使者上书与澹争。帝谕解之。议者谓中国多故，南诏寖强，不若权与和亲。便从之。僖宗庚子广明元年春正月，唐命宗正少卿李龟年来和亲。僖宗辛丑中和元年，上表款附。中和癸卯三年，唐以宗室女为安化长公主，妻隆舜，僖宗乙已光启元年，遣宰相赵隆眉、清平官杨奇鲲、段义宗三人，朝唐帝行在，且迎公主。高骈在淮阳飞章上言：「三人南诏心腹。宜止而酖之。」唐帝从其言。隆眉等死，南诏遂不复振矣。是年昆仑国进美女，舜嬖之。光启二年地震，龙首、龙尾二关、三阳城皆崩。昭宗己巳乾宁四年，隆舜多内嬖，常信谗以诛其下，淫虐日甚。竖臣杨登弑之于东京，在位二十年，子舜化贞立。
|
|-
|}

===Jianning Guo《建宁国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|后汉后皇帝乙巳建兴三年，益州耆帅雍闓，假鬼术杀建宁太守王昂，归东吴，吴王孙权以闓为永昌守。后汉诸葛武侯南征，至白崖，杀雍闓，擒孟获，乃封白子国王仁果十五世孙龙佑那为酋长，赐姓张氏，于白崖筑建宁城，蔚按建宁城废址在今大理府赵州之弥渡。号建宁国，立铁柱蔚按：今弥渡有铁柱宫，铁柱尚存。先为建宁国王张乐进求甫铸，后南诏蒙世隆复重铸，名曰天尊柱，高八尺。并『南中纪功碑』，铭其背曰：「万岁之后胜我者过此」。迨至隋时，行军总管太平公史万岁征南宁夷爨玩，西破三十馀部，至此，见其碑铭，命左右踣之。其碑跌，中复有志曰：「史万岁不应踣吾碑」。万岁惊异，复树碑，祭拜而去。后张龙佑那仍迁国澄江，传三十二世至十七世孙张乐进求，唐太宗己酉贞观二十三年封为首领大将军。后见蒙舍川蒙细奴罗有奇相，遂妻以女，逊国与之。奴罗自称奇嘉王，建号大蒙国，又称南诏。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>eecqacp2ieunnnjs4cz4yibescihvq7</sha1>
    </revision>
    <revision>
      <id>4669883</id>
      <parentid>4669882</parentid>
      <timestamp>2026-09-13T11:17:09Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <origin>4669883</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="60946" sha1="9epgg3dguq26hppxsun67tryfafn1rt" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Unofficial History of Nanzhao (南诏野史)
 | author   = Yang Shen (杨慎)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    =   
}}

== Front Matter ==

# [[Unofficial History of Nanzhao/Translator's Note|Translator's Note]]
# [[Unofficial History of Nanzhao/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Authorship 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|增订南诏野史上卷 明 四川新都杨愼升庵编辑
|
|-
|}

===The Title of Nanzhao 《南诏之称===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Title of Nanzhao 《南诏之称》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|蛮夷称王曰诏。先时滇有六诏，各据其地。六诏中蒙舍诏最强，后并吞五诏，故独称南诏。
|
|-
|六诏考六诏之地，东西四千里，南北二千九百里
|
|-
|蒙舍诏蒙细奴逻立国，居蒙舍川，地在永昌、姚州之间，处五诏之南。后奴逻曾孙皮逻阁并吞五诏，独称南诏。今蒙化厅是邆赕诏丰咩立国，居邓川。今大理府邓川州是施浪诏施望欠立国。居{{浪穹弥茨河蒙次和山，今大理府浪穹县是浪穹诏丰时立国，居浪穹。后其孙铎罗望迁剑川，改称剑浪诏。今丽江府属剑川州地是越析诏波冲立国。亦称摩诏。又号花马国。居嶲州。今丽江府是后，其兄之子于赠渡泸，邑于龙佉河蒙嶲诏嶲辅立国。居越嶲，今四川宁远府，越嶲厅是
|
|-
|}

===The Territorial Divisions of Nanzhao 《南诏分野》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Territorial Divisions of Nanzhao 《南诏分野》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|在天井鬼入参一度，汉书。次鹑首末位晋书。丽中台上位北斗开阳一星。宋书。在地乃梁州裔土，蜀之苑囿。河图纬。
|
|-
|}

===The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周鄯阐国、白崖国、昆弥国。战国时滇国，汉西南夷、益州、白子国。后汉建宁国。晋、宋、齐、梁、陈，宁州。隋昆州。唐初，南宁、六诏，唐文宗太和间，名鄯阐府。宋仍名南诏。元名中庆。明名云南省。
|
|-
|	国朝因之。按：汉武帝元狩元年，彩云见南中，在今大理府赵州之白崖。云南之名始此。唐元宗间问蒙舍诏盛逻皮之相张建一作俭成住何处？曰：「南边云下。」因命为云南。又元宗见祥云起，名祥州。今大理府之云南县也。
|
|-
|}

=== General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|鄯阐国蒙苴颂，昆弥国庄蹻、仁果、龙佑那据于周、秦、汉迄六朝。细奴逻据于唐。郑买嗣、赵善政、杨于贞、段思平、高升泰曁正湻，相继据于唐末迄
南宋。凡历有九姓，而雍闓、孟获不与焉。段氏与南宋理宗壬子湻佑十三年为蒙古所灭，而段实于理宗景定二年袭总管，传十二世，明太祖壬戌洪武十五年平云南，擒段世，并段段明之二子苴仁、苴义。赐苴仁官雁门卫镇抚，苴义官武昌卫镇抚，段氏之世土方绝，而又别封其族人段保为大理府云龙州土知州。国朝尚有袭土职者。
|
|-
|}

=== Titles and Official System of Nanzhao《南诏称谓官制》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Titles and Official System of Nanzhao《南诏称谓官制》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|南诏称帝曰骠信，王曰诏，自称曰元，称后曰信么，亦曰九么，妃曰进武，兄曰容，弟曰钟，下曰昶。其设官则有把国事八人，曰坦绰，曰布燮，曰九赞，谓之清平官。曰酋望，曰正酋望，曰员外酋望，曰大（将军）〔军将〕，曰员外。又设九爽之名，爽，省也。功爽主官人，宗爽主户籍，万爽主财用，慈爽主礼，引爽主宾客，幕爽主兵，罚爽主刑，厥爽主工作，禾爽主商贾，皆清平官、酋望、大军将兼之。以清平官子弟为羽仪长八人，清平官见王不得佩剑，惟羽仪长佩之。又有六曹长二人，曹长有功升大军将，凡十二人。又立三托：巨托主仓廪，气托主马，禄托主牛。大府主将曰演习，副曰演览；中府主将曰缮裔，副曰缮览；下府主将曰澹酋，副曰澹览；小府王将日幕撝，副曰幕览。每府有陀酋，陀酋卽掌书记判官之类。外有八节度使：日弄栋节度使，今楚雄府姚州。曰银生节度使，今景东厅及鎭沅州地是。曰永昌节度使，今永昌府是。曰丽水节度使，今丽江府是。曰剑川节度使，今丽江府剑川州是。曰东川节度使，今东川府府是。曰通海节度使，今临安府通海县是。曰拓东节度使。今云南府昆阳州北平定乡，蒙氏子凤伽异曾筑城于此地。又有二都督：曰会川都督，今四川宁远府会理州地是。曰通海都督。又设十睑，蛮语谓州为睑。苴音斜。羊睑，又名羊睑，卽今大理府太和县。赵州睑，今大理府赵州。白崖睑，又名勃弄睑，今赵州之白崖。，云南睑，今大理府云南县。蒙舍睑，今蒙化厅。大厘睑，又名史睑，今太和县喜州。邆川睑，今大理府邓川州。品澹睑，蒙秦睑，矣和睑。三睑未详其地。○蔚按：别本十睑中苴羊睑、赵州睑、白崖睑而下，作义督睑，今剑川州；威远睑，今普洱府威远厅南；河东睑，末详其地；越睑，今永昌府腾越州；北方睑，又名成偈睑，今永北厅；楼头睑，今四川叙永厅，属永宁县；路睑，今楚雄府广通县；与云南睑以下七睑异。○按：又考此七睑中，其越睑、北方睑、楼头睑、路睑凡四睑，见于『汉地里志』及『唐书?南蛮传』中，睑并作赕，音闪，字旣不同，音又各异，似非列于十睑之数。凡人丁壮者皆为战卒。王之亲兵曰朱弩佉苴，音蛆。按：元微之白乐天乐府皆作佉嗟，未审孰是。佉苴，韦带也。每兵百人置罗苴子统一人，戴朱鞮鍪，负犀革铜盾而跣足。自大军将以至曹长，皆系金佉苴尚绛紫，有功加锦，又有功加金波罗。卽虎皮。民兵号白衣，凡民兵出以望苴蛮为先驱。
|
|-
|}

===Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|因远部。威远睑治，其地总名和泥，今元江府是。休腊部。今临安府河西县。嶍峨部。今临安府嶍峨县。屈中部。今临安府阿迷州。溪处甸部、伴溪落恐部。今倶为长官司，属临安府。铁容甸部。今为亏容长官司。官桂思陀部。今为思陀甸长官司，皆属临安府。王弄部、强现三部。今属开化府。师宗部。今广西州师安县。弥勒部。今广西州弥勒县。吉输部、袖恶部。倶在弥勒县地。维摩部。卽广西府维摩州。州裁，今属广西州地。罗雄部。今曲靖府罗平州。纳垢州。今曲靖府马龙州。落温部。今曲靖府陆凉州。磨弥部。今曲靖府沾益州。仁德部。今曲靖府寻甸州。夜苴部卽曲靖府亦佐县，县裁，今归罗平州。强宗部。卽澄江府阳宗县，县裁，今归河阳县。步雄部。今澄江府江川县。罗伽部。卽步雄部分地。休制部。今澄江府新兴州。落蒙州。今澄江府路南州。弥沙部、邑市部。皆落蒙部子孙分治之。阳城堡部。今云南府晋宁州。罗部。今云南府罗次县。乾矢部、罗婺部。倶在武定府曲州，州裁，今属武定州。华竹部。今武定州元谋县。洪农碌券部。今武定州禄劝县。掌鸠法块部在禄劝县城东五里。○以上三十五部在迤东地。白鹿部。今楚雄府。谋统部。今丽江府鹤庆州。○以上二部在迤西地。
|
|-
|}

==Nanzhao through the Generations《南诏历代》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Nanzhao through the Generations《南诏历代》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|白古记：西天天竺摩竭国阿育王骠苴音斜。低娶欠蒙亏为妻，生低蒙苴。苴生九子，长子蒙苴，附罗十六国之祖；次子蒙苴廉，吐蕃之祖；三子蒙苴诺，汉人之祖；四子蒙苴酬，东蛮之祖；五子蒙苴笃，生十二子，七圣五贤，蒙氏之祖；六子蒙苴托，狮子国之祖；七子蒙苴林，交趾国之祖；八子蒙苴颂，白子国仁果之祖；九子蒙苴閦初六切。白夷之祖。○『哀牢今永昌府。夷传』：哀牢蛮蒙伽独捕鱼易罗池在永昌府城南。溺死。其妻沙壹一作壶。往哭之水边，触一浮木，有感而妊，产十子。后携子至池上，木化为龙，人言曰：「我子安在？」九子惊走，独季子背龙而坐，龙舐其背。蛮语谓背为九，坐为隆，故名之曰九隆氏。哀牢山一名天井山，在永昌府。下有妇名奴波息，生十女，九隆弟兄娶之，立为十姓：董、洪、段、施、何、王、张、杨、李、赵，皆刻画其身象龙文，于衣后著尾。子孙繁衍，居九龙山山在永昌府城南。溪谷间，分九十九部，而南诏出焉。
|
|-
|}

===Shanchan Guo《鄯阐国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shanchan Guo《鄯阐国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周时立国，年代久远，其姓名世次莫考。
|
|-
|}

===Baiya Guo《白崖国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baiya Guo《白崖国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|西天天竺摩竭国阿育王低蒙苴第八子，蒙苴颂居白崖，因地名，号白崖国，传世莫考。后昆弥氏继之，号昆弥国。
|
|-
|昆弥国一名拜国。
|
|-
|昆弥氏，传世姓名莫考。战国时，楚将庄蹻据滇，并有其地，号滇国。
|
|-
|}

===Dian Guo《滇国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dian Guo《滇国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|战国时，楚顷襄王命将庄蹻范蔚宗后汉书作庄豪。将兵循江上，略巴、蜀、黔中以西，蹻至以兵威畧定滇地属楚。欲归报，会秦司马错攻楚，黔中道塞。蹻遂以其众王滇，号滇国，踞之。后有王常羌者好佛，国势不振。法令不行，国人遂推白崖国蒙苴颂之后，白饭王之裔仁果为王，治白崖，于是两国角立。后仁果奉汉，封为白子国。
|
|-
|}

===Baizi Guo《白子国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baizi Guo《白子国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|汉武帝通西南夷，遣使至滇，求身毒国。滇王常羌问使者曰：「汉孰与我大？」使者还报，武帝怒其言不逊。时白崖国蒙苴颂之后，天竺国白饭王之裔仁果者，为众所推立于白崖。武帝乃册封仁果为王，号白子国。后迁于澄江，今澄江府。迨龙佑那继之，号建宁国。○又一说：白子国之先，有阿育国，王能乘云，上天娶天女，生三子，长季二子封于金马、碧鸡，独封仲子于苍洱之间，崇奉佛敎，不茹晕，日食白饭，人因称为白饭王。迨后有仁果者，汉封为滇王，号白子国。又十五世至龙佑那，后汉诸葛武侯南征，次白崖，以佑那为酋长，赐姓张氏，仍统其民，号建宁国。
|
|-
|}

===Jianning Guo《建宁国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|后汉后皇帝乙巳建兴三年，益州耆帅雍闓，假鬼术杀建宁太守王昂，归东吴，吴王孙权以闓为永昌守。后汉诸葛武侯南征，至白崖，杀雍闓，擒孟获，乃封白子国王仁果十五世孙龙佑那为酋长，赐姓张氏，于白崖筑建宁城，蔚按建宁城废址在今大理府赵州之弥渡。号建宁国，立铁柱蔚按：今弥渡有铁柱宫，铁柱尚存。先为建宁国王张乐进求甫铸，后南诏蒙世隆复重铸，名曰天尊柱，高八尺。并『南中纪功碑』，铭其背曰：「万岁之后胜我者过此」。迨至隋时，行军总管太平公史万岁征南宁夷爨玩，西破三十馀部，至此，见其碑铭，命左右踣之。其碑跌，中复有志曰：「史万岁不应踣吾碑」。万岁惊异，复树碑，祭拜而去。后张龙佑那仍迁国澄江，传三十二世至十七世孙张乐进求，唐太宗己酉贞观二十三年封为首领大将军。后见蒙舍川蒙细奴罗有奇相，遂妻以女，逊国与之。奴罗自称奇嘉王，建号大蒙国，又称南诏。
|
|-
|}

==Nanzhao《南诏国》==
===13 Generations of Nanzhao 《南诏大蒙国传十三世》 ===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ 13 Generations of Nanzhao 《南诏大蒙国传十三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|细奴一作农。逻一作罗。　伪谥高祖奇嘉王
|
|-
|细奴逻，又名独罗消，西天天竺摩竭国阿育王低蒙苴第五子蒙苴笃之三十六世孙。生有奇相。唐太宗贞观初，其父舍龙尨，又名龙伽独，将奴逻自哀牢避难至蒙舍川，耕于巍山。今蒙化厅之巍宝山。一日，有老僧，美髯，冠赤莲冠，披袈裟，持钵至奴逻家乞食。时奴逻与子逻盛炎方耕巍山之下，其姑与妇将往饁。见僧乞食，遂食之。再炊往饁，僧坐不去。姑妇持饷中道，僧已在彼，复乞食，姑妇又食之。返而复炊，持饁至巍山，则见僧坐盘石上，前有靑牛，左白象，右白马，上覆云气。云中二童子，一执铁杖于左，一执方金镜于右。姑妇惊喜，复以所饷供之。僧问何所愿？姑妇不知对。僧曰：「奕叶相承」。及趣奴逻等至，则但见一人持钵，坐五色云中，而盘石上惟馀衣痕及牛象马之迹耳。奴逻素有祥异，会唐封首领大将军建宁国王张乐进求，以诸葛武侯所立白崖铁柱，岁久剥蚀重铸之。因社会祭柱，柱顶故有金镂鸟，忽能飞，集奴逻左肩，相诫勿动，八日乃去。众骇异，谓天意有属。进求遂妻以女，举国逊之。于唐太宗己酉，贞观二十三年卽位，年三十二岁，建号大蒙国，称奇嘉王，据南诏。高宗庚戌永徽元年，建都蒙舍川，于巃｛山＋于｝山在今蒙化厅西北三十五里。筑巃山＋于城。永徽癸丑四年，遣逻盛炎入朝唐，诏授奴逻为巍州今蒙化厅刺史，赐以锦袍。大勃弄今大理府赵州白崖。酋杨承顚寇麻州，在今曲靖府马龙州城北里许。唐命郞州唐贞观初，分牂牁郡北界置郞州，后改名播州，卽今贵州遵义府。又有郞州，在今云南县地。道行军总管赵孝祖讨之。孝祖先入小勃弄，今云南县地。酋长没盛迎战，孝祖斩之。进至大勃弄，攻其城，破之，擒杨承顚，改云南县为匡州，领勃弄、匡州二县。高宗显庆二年，凤鸣于浪穹罗浮山，乃改名为凤羽山，在大理府浪穹县西南三十里，又名鸟吊山。见『水经注』。封十二圣贤为十二山神。时澄江人波罗旁有经济才，用为文臣；郭郡矣素以勇略闻，用为武臣。又有杨波远者，相传为东汉时人，常骑三角靑牛，号神明大士，能知盐泉，滇中盐泉多为波远所开创。奴逻在位，遵唐正朔。高宗甲戌上元元年，奴逻卒，在位二十六年，子逻盛炎立。
|
|-
|逻盛炎又名逻晟。伪谥世宗兴宗王。
|
|-
|	逻盛炎。唐高宗甲戌上元元年卽位，年四十岁，以张建成为相。明年，盛炎临朝，元宗壬子先天元年，姚州蛮叛归吐蕃。唐命御史李知古讨之，筑城立州县。知古诛豪杰，掠子女，蛮怨，引土蕃，攻杀知古，于姚嶲路绝，而盛炎独奉唐正朔。是年，盛炎卒，在位三十九年，子盛逻皮立。
|
|-
|}


===Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|盛逻皮，唐元宗壬子先天元年卽位，年四十岁。明年为元宗癸丑开元元年，唐授逻皮为特进，封台登郡王今四川宁远府冕宁县地。设官征商税。开元二年，遣张建成入朝于唐。立土主庙。开元九年，皮叛唐。开元十四年，立庙祀晋右将军王羲之为圣人。元宗戊辰开元十六年，逻皮卒，在位十六年，子皮逻阁立。
|
|-
|皮逻一作罗阁石刻作归义王魁乐觉封云南王。
|
|-
|皮逻阁，唐元宗戊辰开元十六年卽位，年三十一岁。开元十八年，灭五诏，自称南诏王。先是，蒙氏恐三十七蛮部不服，选亲族为五诏。未几五诏抗命，逻阁遂赂剑南节度使王昱，求合六诏为一。昱奏于朝，许之。逻阁乃豫建松明大楼，祀祖于上。使人谕五诏曰：「六月二十四日乃星回节蔚按『大理郡志』汉元封间，叶楡妇阿南者为酋长，曼阿娜之妻。娜为汉将郭世忠所杀，欲妻南。南曰：能从三事，当许汝一作幕次祭故夫；一焚故夫衣，易君新衣；一令国人皆知我以礼嫁。忠如其言。明日，聚国人张松幕祭其夫。下置火，南藏刃出，俟火炽焚夫衣，卽引刀刃自断其颈，仆火中，时六月二十五日也。国人哀之，故岁以是日燃炬吊之，名为星回节云。是又当为二十五日。当祭祖，不赴者罪。」四诏听命。惟越析诏波冲之兄子于赠，远不赴会，而邆赕诏丰哶孙｛辵＋皮｝逻邆之妻慈善者，止逻邆勿赴。邆不听。慈善不得已，以铁钏穿于邆臂而行。二十四日，逻邆及施浪诏施望欠弟施望千、浪穹诏丰时孙锋罗望、蒙嶲诏嶲辅子罗原皆至逻阁所。逻阁偕登楼祭祖，祭后享胙食生饮酒，迨晚，四诏尽醉。逻阁独下楼，焚钱遽纵火，火发，兵围之，四诏皆焚死。逻阁遣使至四诏所，报焚钱失火，四诏被焚，状令各诏收骨。四诏妻至，莫辨其骨。独慈善因铁钏得焉，携归葬之。逻阁旣灭四诏，取各诏宫人，念慈善慧而甚美，遣兵围其城，迫取之。慈善曰：「吾岂忘夫事仇者？」闭城坚守，半月城中食尽，慈善度不能支，卽自杀，时七月二十三日也。逻阁嘉其节，乃封赠为宁北妃，并旌其城曰德源城。城废址在今大理府邓川州城东北二里许。开元戊寅二十六年，逻阁破吐蕃及弥蛮，入朝，元宗礼之，加封为特进，云南王，越国公，开府仪同三司，赐名归义，并锦袍金钿带七事。王归国，以兵逐洱河蛮，筑太和城，今大理府城南十五里太和村地是。又筑大厘城今大理府城北四十里喜州是。守之，尽有云南之地。唐授王子阁逻凤右领军卫大将军兼阳瓜州刺史。开元二十七年，明矫叛，破剑川、浪穹、永昌。开元二十八年，王讨朋矫，平之。开元辛已二十九年，王自蒙舍川迁居太和城，立龙首、卽今上关。龙尾卽今下关。二关。唐加阁逻凤为左领军卫大将军。元宗癸未天宝二年，筑羊苴哶城于太和城之北。卽今大理府城。唐迁阁逻凤为左金吾卫大将军，寻拜特进都知兵马大将军。天宝甲申三载，西方进狮子皮。唐加阁逻凤为上柱国。天宝乙酉四载十月，城永昌。天宝丙戌五载，王遣孙凤伽异入唐，唐授伽异为鸿胪少卿，妻以宗室女，赐龟兹乐一部，元宗戊子天宝七载，王卒，在位二十年，子阁逻凤立。
|
|-
|阁罗凤一作觉乐凤。按：『德化碑』云：「家居阁罗凤」，则是取地名以为名也。袭封云南王，伪谥神武王。始建元。
|
|-
|	

阁罗凤，唐元宗天宝戊子七载卽位，年三十六岁。唐遣中使黎敬义持节册凤袭封云南王，敕置阳瓜州于蒙舍川，加授

凤伽异为上卿兼阳瓜州刺史，都知兵马大将军。天宝庚寅九载，王率妻子往谒都督李宓，过云南，太守张虔陀私之，又多徵求。王表虔陀之罪，中官贾奇俊抑之，不得达。王复遣将军杨罗顚等连表控告。元宗仍不省。凤怒，遣大将军王毗双、罗时等发兵攻虔陀。虔陀饮鸩死；遂取姚州，并夷州三十二。获唐嶲州西泸令郑回以归，爱其才，用为清平官。天宝辛卯十载，唐命剑南节度使鲜于仲通将兵八万征云南。凤赴泸南在楚雄府姚州之城北一百五十里。谢罪，愿还所俘掠，请罢兵。仲通不许，分三道而进。仲通自南溪路，大将李晖自会同路，都督王知进自步头路。今临安府地。凤就安宁，再伸衷悃。仲通不听，兵至曲州、靖州。二州今为曲靖府地。凤复遣首领杨子芬、参军江如之赍状，言若不罢兵，卽当归吐蕃，恐云南非唐有。仲通终不许，囚其使，进薄白崖城。别遣大将王天运统师绕出点苍山后。凤遣

凤伽异及大军将段俭魏迎山后师，自逆战于西洱河。唐兵大败，死者六万人，王天运战殁，仲通仅以身免。凤乃叛唐，建元长寿。遣弟阁陂和尚及子铎传、酋望赵佺邓、杨传磨侔等，并子弟六十人献凯吐蕃。陂有神术，人马往来吐蕃，不过朝夕之顷。天宝十一载正月一日，遣宰相倚祥叶乐持金冠、锦袍、金宝带、金帐状、安扛伞鞍、银兽器皿、珂贝、珠毯、衣服、駞马、牛鞻等物至邓川，以凤为兄弟之国，册为赞普钟南国大诏，给金印，称东帝。并授凤伽异大瑟瑟告身，都知兵马大将。凤遂改是年为赞普钟元年。发人口百户于浪穹，筑白崖睑城，又遣兵攻掠安宁。天宝甲午十三载六月，唐命前云南郡都督兼侍御史剑南留后李宓、广府节度使何履光等，率十道兵再征云南。兵逼邓川，凤遣凤伽异、段俭魏迎战于江口。时神川都知兵马使论绮里徐救兵已至巴蹻山，遂诱宓深入，内外夹击。宓粮尽，士卒饥疲，引还。凤以精兵追战，唐全军覆没，李宓被执，沉江死，何履光遁去。凤因进取嶲州会同郡，据清溪关，以破越析。此二役也，皆凤弟阁陂和尚及凤妃白氏行妖术，展帕拍手而笑，韩陀僧用钵法，以故唐兵再败。时唐先后丧师已二十馀万，凤乃敛战胔，筑京观于龙尾关河尾，名万人冢，立碑大书「唐天宝战亡士卒之墓」。而唐宰相杨国忠更揜败以捷闻，叙战功。令清平官郑回撰『德化碑』，唐流寓御史杜光庭书。立石太和国门外，明其不得已叛唐归吐蕃之故。天宝乙未十四载冬十一月，东平郡王安禄山反于范阳，凤乘机以兵取蜀卭州，筑卭子城，及丽水金宝城。升段俭魏为清平官，赐名忠国，旋拜相国。代宗甲辰广德二年，羊苴哶城成，凤名之曰大理城，又名紫城。代宗乙巳永泰元年凤伽异筑云南城卽今云南府省城。又筑拓东城，今云南府昆阳州北平定乡。遂以兵攻陷曲靖。代宗丁已大历十二年，永昌牛生三角，羊生四角，鸡九足，井有光。建观音寺于白崖。先是，逻盛炎时，相国张建成欲于白崖建寺，卜之吉。又地下有三戳观音，上截在西，中截在东，下截在东南。因盛炎旋卒，不果建。至是建寺，掘之果然。代宗戊午大历十三年，阁罗凤卒，在位三十年。因子凤伽异先死，后追谥悼惠王。孙异牟寻立。
|
|-
|异牟寻改国号曰大理国。封云南王，又封南诏王　伪赠廪孝桓王
|
|-
|异牟寻，唐代宗戊午大历十三年卽位，年二十四岁。明年改元见龙，又改上元，率兵三万取蜀为东府，又连土番入寇。唐命神策都将李晟击破之。师还，自称南诏王。德宗甲子兴元元年，牟寻迁居史城，卽大厘城。改号大理国，自称日东王。封岳读，以叶楡今大理府。点苍山为中岳，乌蛮今东川府。乌龙山一名绛云弄山，在今禄劝县东北三百里。为东岳，银生府今景东厅。蒙乐山一名无量山，在厅北九十里。为南岳，又封南安州今楚雄府属。神石亦为南岳，越赕今永昌府腾越州。高黎贡山一名昆仑隅，在腾越、潞江之间。为西岳，嶲州今丽江府是。雪山一名玉龙山，在府西北二十里。为北岳。封金沙江源出吐蓄旄牛徼外犂牛石下，本名犂牛河，又名犂水，讹为丽水。经丽江府、鹤庆州、姚州而东北达于四川马湖府之马湖，卽『山海经』所谓若水。『水经注』云：若水经云南之遂久县，卽今金沙江巡检司地。昔黄帝长子昌意德劣，不足绍承天位，降居斯水为诸侯，娶蜀山氏女，生颛顼于若水之阳，疑卽其地也。祀在武定州，兰沧江源出吐蕃鹿石山下，本名鹿沧，又名兰沧。兰沧讹为浪沧。自丽江府度云龙州至永昌府，东经顺宁府，达于车里，过交趾地而入于南海。祀在丽江府，黑惠江在顺宁府之东入狼沧江，而达于南海。祀在顺宁府，怒江源出西域雍望，奔流而下，深不可测。夏月多瘴，经怒夷地入丽江府境野人界。至永昌府境，乃名潞江。祀在水昌府，为四渎，各建神祠。又立三皇庙。德宗丙寅贞元二年，设官立九爽三托。考疆域，其地东至于铜柱、铁桥、蟠桃、玉楡，东南至于交趾国，南至于骠国，西南至于木落山，西至于太石，西北至于吐蕃，北至于神川，东北至于黔巫。八分之地，属以八演，皆中国降人为之经画者。贞元丁卯三年，寻居大理城。命子弟师事郑回。时寻苦吐蕃徵求无厌，会李泌劝德宗招云南以断吐蕃右臂。帝从之，命韦皋为西川节度使，皋受命招抚群蛮。郑回因说寻归唐，寻以为然。皋遣谍者致书于寻，吐蕃知而疑之，乃责南诏大臣为质。寻愈怨。于是，决计归唐。皋以闻，德宗乃命皋作书谕寻。是年四月，吐番破蜀，来征兵，蔚按：卽吐蕃劫浑瑊清水盟之岁。寻谢绝之。贞元五年，寻遣乌蛮勿邓大鬼主苴梦冲、两林都大鬼主直那时聘于皋，因入朝。皋遣其属崔佐时报之。时吐蕃使数十人先在，佐时至，寻令更衣入。佐时不可，曰：「天朝大使。岂衣夷衣？」寻不得已，夜迎之。佐时至，大宣诏旨，令寻斩番使，去其所立之号。寻遂与佐时盟于点苍山下。贞元九年，寻遣使上表，请从韦皋袭吐蕃。诏册封为云南王，以韦皋为云南安抚使。王遣使诣皋，献夷中歌。贞元十年，吐蕃徵兵于王，王阳示寡弱，以兵三千应之，自将数万人踵其后。正月，袭吐蕃，战于神州，断铁桥，在巨津废州，今丽江府西北地。取十六城，俘其五王，降众十馀万，获军资甲仗无算。遂遣弟凑罗栋、清平官尹仇宽献捷于唐，并献地图、纳贡及吐蕃所给金印，请复号南诏。于是，唐以祠部郞中袁滋为中丞，赐金紫充册使。赐王银窠金印，印文曰：「贞元册南诏印」。王北面跪受。宴使者，出元宗天宝五载所赐王父凤伽异银跳脱马头盘数物，并指老笛工、歌女曰：「皇帝所赐龟兹乐，惟二人在耳！」使者日：「南诏世荷唐恩，当深思祖考子孙勿替，尽忠皇唐。」王对曰：「敢不敬使者之命。」随遣清平官尹辅首入谢，献铎鞘、郁刀、生金、瑟瑟、牛黄、氎、纺丝、越赕绕伦马。蔚按：铎鞘，疑当作择矟，状如残月，有孔旁达，出丽水，饰以金，月祭之血，所击无不洞。段柯古『酉阳杂俎』云：南蛮有毒槊无刀刃，状如朽铁，中人无血立死。言自天而下，入地丈馀，祭地乃掘得之，云云。疑卽铎矟，毒为铎字之讹，槊字本同矟宇也。郁刀铸时以毒药并冶，取莹耀如星者，凡十年乃成，淬以马血，镂金犀饰镡首，伤人卽死。因浪人所铸，又名浪剑，夷中甚宝之。七月，又攻吐蕃，并破施蛮、顺蛮，施蛮、顺蛮卽施浪、浪穹二诏之后，自南诏并吞五诏，五诏之后不复称诏，止称蛮。俘其王置白崖城。贞元十二年，取越赕，置软化城。贞元十四年，请以大臣子弟质于朝，韦皋却之。固请，乃尽舍成都，遣就学。贞元十五年，王开白国北方赕地，今永北厅。徙弥河白蛮及罗落摩蛮实之，号剑羌。是年，王从韦皋再败吐蕃于铁桥。初，王谋击吐蕃，以邆川、卽今邓川州。宁北卽今浪穹县。等城当寇冲，乃峭山深堑，修战备。至是吐蕃谋袭南诏，王告于皋，遣将屯黎州、嶲州以应之。吐蕃引兵攻嶲州，皋严兵以守，别遣将袭击，降其帅，吐蕃惧，退至铁桥。王令人毒其水，吐蕃人马多死，退屯三泸水，王与皋部将杜毗罗击败之。贞元十六年，王率子寻阁劝入朝于唐，召对延英殿，进奉圣乐舞，德宗御麟德殿观之。贞元十七年，王夜绝泸水，斩吐蕃屯卒，又合鬼主破之于泸西。吐蕃大惧，欲悉师收嶲州，以绝南诏。王谓韦皋曰：「吐蕃声取嶲州，实窥云南，请进军羊苴咩城。」皋督诸将分道与王会，陈兵深入，拔木波城。前后凡克城七，焚堡百五十所，斩获无算，生擒论莽热，献于唐，并进铠甲十五万。皋班师，帝遣中使慰抚王。王自是比年贡方物，唐帝深礼之焉。贞元十九年，王封云南金马碧鸡二山之神为景帝，建妙音寺塔，筑大理雪峰长城。宪宗戊子元和三年七月，王卒。唐遣使祭吊，在位三十年，子寻阁劝立。
|
|-
|寻阁一作觉劝又名新觉劝。　袭封南诏王　伪谥孝惠王
|
|-
|寻阁劝，唐宪宗戊子元和三年卽位，年三十一岁。唐册劝袭封南诏王，赐元和金印。宪宗己丑元和四年正月，改元应道，群臣上尊号曰骠信，以鄯阐为东京，大理为西京，重修曲靖崇真寺。寺为晋代所建。十一月王卒，在位一年。子劝龙晟立。
|
|-
|}

===Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝龙晟，唐宪宗己丑元和四年卽位，年十二岁。唐册袭封南诏王。明年，改元龙兴。铸佛三尊，送佛顶峰寺，用金三千两。元和九年，晨寇嘉定州，有飞天神兵破之。先是，节度使杜元颖守成都时，时滇兵至嘉定之沐源州，忽自惊溃。蜀军获一夷卒问之，云适见遍山神兵，一神将长斧坐二鬼上，声若迅雷，故尔惊走。至是神复现形，自后追杀，卽时死酋长二人。盖嘉定向有飞天神庙，两破滇兵者，皆此神也。宪宗丙申元和十一年，晟淫虐失道，弄栋节度使王嵯巅弑之，时年仅十九岁，唐命少监李铣祭吊，在位七年，弟劝利立。
|
|-
|}

===Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝利，唐宪宗丙申元和十一年卽位，年十五岁。唐册袭封南诏王。王嵯巅东寇。明年，改元全义。元和十三年，厚赏王嵯巅，赐姓蒙，封太容。元和十四年，废王嵯巅，赦其罪，命敬信三宝，为清平官。元和十五年，又改元大丰。重修崇圣寺。五月，大雨霖，龙首、龙尾二关倾。除洱河水怪，建龙屋塔。高十二丈。按：『白古记』：唐时洱河有妖蛇，名薄劫，兴大水淹城。蒙国王出示：有能灭之者，赏半官库，子孙世免差徭。部民有段赤城者愿灭蛇，缚刃人水，蛇吞之，人与蛇皆死，水患息。王令人剖蛇腹，取赤城骨葬之，建塔其上，毁蛇骨灰塔，名为灵塔。在今大理府城南龙尾关内点苍山马耳峰下羊皮村。每年有蛇党起风来剥塔灰。时有谣曰：赤城卖硬土。今『龙王庙碑』云：洱河龙王段赤城云。永昌生两头牛。穆宗甲辰长庆四年，赐南诏王金印。是年王卒于东京，在位八年，弟丰佑立。丰佑慕中国之风，独不肯连父名。丰佑石刻作劝丰佑　　册封滇王　　伪谥昭成王
|
|-
|	

丰佑，唐穆宗甲辰长庆四年卽位，年七岁。唐遣京兆少尹韦审规持节册封为滇王。王遣洪成酋等人谢。明年，改元保合，又改元天启。西僧赞陀啒哆建鹤庆元化寺。先是，鹤庆地水淹，僧杖刺东隅泄之。水中得樟木，刻为佛，咒之忽灵，远近名曰活佛。按：活佛，后至明成化间，福建莆田林俊为云南宪副闻之，亲至寺中，将佛火之，得金数百两入官，又毁他寺三百，人呼为林劈佛。建常平仓，筑邓川城。敬宗乙巳宝历元年，重修大理崇圣寺一名三塔寺。成先是，王嵯巅广寺基方七里。圣僧李成眉贤者建立三塔，高三十丈。佛一万一千四百，屋八百九十，铜四万五百九十筋。元和十五年经始，至是工竣。塔顶旧有铁柱款识云：「贞观六年尉迟敬德监造」，盖寺之建久矣。重修云南东寺塔，高百五十尺，西寺塔高八十尺，二寺亦贞观间将作大匠尉迟敬德所建。文宗丁未太和元年，王母出家，法名惠海。太和二年，用银五千，铸佛一堂，废道敎。太和己酉三年，僧梦岛造永昌卧佛，长丈六。六月朔，星落如雨。命王嵯巅等寇蜀。先是，西川节度使杜元颖失士卒心，军逃入南诏，因此知蜀虚实。佑遂遣嵯巅等攻蜀，陷嶲、戎、卭三州，攻成都，止西郛十日，掠经书、宝货、子女无算，蜀中残敝。并寇梓州、蜀州。佑上表于唐，请诛元颖。唐改云南为鄯阐府。卽今云南府省城。太和四年，唐贬杜元颖循州司马，以义成节度使李德裕为西川节度使。裕至西川，建筹边楼，日召习边事者访问，凡山川险要，南道与蛮相入者图之左，西道与吐蕃相接者图之右，不啻身尝经历焉。乃奏请留北兵以重镇守，修甲胄、备器械。率户二百取一人习战，作雄边子弟等十一军。筑仗义、御侮、柔远诸城以扼要害，复卭崃关，徙嶲州治台登，以夺蛮险。令转卭、雅粟以十月而运，先夏而至，人不苦瘴，边境始安。至是使人于佑，责归所俘。太和五年五月，佑归所俘西川四千人于德裕。太和六年，佑掠骠国民三千，徙之拓东城。武宗乙丑会昌元年，佑遣军将晟君筑横渠道自磨用江至于鹤拓，灌东皋及城阳田，与龙佉江合流入于河，谓之锦浪江。又潴点苍山玉局峰顶之南为池，谓之高河，又名冯河。更导山泉共泄流为川，灌田数万顷，民得耕种之利。会昌六年九月，佑攻陷安南，经略使裴元裕死之。宣宗丁卯大宗元年，佑妃卒，佑郁郁不乐，臣下请选妃女备后宫。得罗部今云南府罗次县。一美女进之，有宠。女好佛，建罗次寺，至今灵异。六月大旱，佑令僧寿海祈雨。僧曰：「昔汤旱七年，六事自责，天雨七日。今王酒色妄杀，天怒不雨。王如改悔，天雨自至，何以祈为？」佑如僧言，自责自改，数日果雨。佑女至崇圣寺进香，回至城西，为一乘白马人摄去，寻之不得。佑告于西僧赞陀啒哆，哆曰此山神也。乃设灯照之，果在苍山下。哆怒欲行法，移山于河。山神惧，献宝珠供佛，佑乃已。大中十二年，佑遣段酋迁陷安南都护府。遣段宗榜救缅。榜，汤今云南府宜良县地。人，佑之勇将。先是，狮子国侵缅；屡求救，至是许之。按：缅甸卽汉之掸国，唐之骠国，其历代莫考。当宋元之时，屡败王师。明太祖洪武十年，缅头目招扳南进贡。十九年，使行人司钱古训赍诏立宣尉司。二十年，缅犯景东。二十一年，犯他郞甸，沐英命都指挥宁正平之。三月，犯定边，沐英同都督冯诚平之。景泰三年，王骥赏缅孟养地。缅喜，乃擒献麓川贼。嘉靖初，缅火烧赍金牌官，中终年猖獗海上，遂至难制。○考自永昌府腾越州入缅，止三十四程。腾越一日南甸、一日罗必斯、一日郞、一日甸头、一日甸尾、一日蒙腰、一日甸蓝、一日蒙怜路、一日空地、一日蒙来路、一日大市、一日龙江、一日锅地、一日人列渡、一日江头城、一日景怜、一日及、一日马来城、一日赖当、一日山头、一日甸头、一日阿只、一日吴细辰、一日折弓、一日阿越。由阿越下水，九日卽至缅城。其地有五大城，江头、太公二城之外，又有马来、安正国、蒲甘缅王三城。酋住金楼，民住竹楼。其下称酋为卜剌浪，称酋妻为米泼剌。酋出人乘轿，水有舟筏。官名有招孟、招彔、招刚三等。官无大小，倶金银花宝带。无弓箭。其水有金沙江，险恶，缅恃以为固。涸时，亦仅五里。俗敬佛，重罪对佛发誓，凭僧处断。○入缅又有三道：一由潞江西上；一由腾越七日至麓川；一由景东从木通甸至湾甸渡入芒市，十日至麓川。○此外从潞江上流蒙来渡至景乐沿河有小渡十馀处，皆可通。又有三道：一由天步马，一由湾甸，一由阿郊地界，皆可入缅。宣宗己卯大中十三年，陷播州。李德裕旣贬死，西川节度使所任皆非人，侥佯边功，发兵十万袭滇，自建昌入，佑命子世隆为坦绰，同王嵯巅迎战于古宗，今丽江府铁桥以北地。杀唐兵数万人，立铜柱于界上。世隆之母，佑妃也，出家号师摩矣。尝随佑至罗浮山白城，建一寺，南壁画一龙，是夜龙动，几损寺，妃乃复画一柱锁之，始定。按：妃本渔家女，喜浴。为妃后，仍常泛舟西洱河，屏人潜浴于水，感金龙与交，生世隆。隆七岁，拳握始开，有文在其掌曰：通番打汉。古宗之战，唐帝惧世隆为患，妻以宗室女，伺察其所为。女以世隆年庚潜送于帝。帝使太史推之，知其感龙精而生。是年，丰佑卒于东京，在位三十五年。子世隆立，以王嵯巅摄政。段宗榜救缅，回至腾越，闻佑卒，世隆立，嵯巅摄政，移书王嵯巅曰：「天启不幸，驾崩嗣幼，闻公摄政，国家之福。榜救缅以败狮子国。缅酬金佛，当得敬迎。奈中国无人，惟公望重。榜抵国门之日，烦亲迎佛，与国增光。」云云。嵯巅不知是谋，至日迎之。榜令巅拜佛，突斩之于佛前。讨其弑劝隆晟之罪也。榜熔佛得金数千两。时有缅人奉香火者在榜，默祝曰：「愿世代奉敬，今不如愿，惟愿世尊轮生，灭彼国祚。」后果生郑买嗣篡国，灭蒙氏。
|
|-
|世隆『唐书』作酋龙。　　伪谥景庄皇帝僭称帝始此，以后郑、赵、杨、段、高五姓之国咸效之。
|
|-
|世隆，唐宣宗己卯大中十三年卽位，年十六岁。明年，为懿宗庚辰咸通元年，改元建极。改西京曰中都，东京曰上都。先是，德宗贞元间，西川节度使韦皋开道通南诏，令岁入贡。异牟寻、寻阁劝二世事唐唯谨，迨劝龙晟及丰［佑］，又数数扰边，大为唐患。又以世隆之名犯太宗、元宗庙讳。唐不册封，隆益致怨望。至是自称皇帝，遣兵取乌蛮、僰、爨之地，置东川郡。前节度使杜悰变韦皋制度，侵扰蛮中。隆绝朝贡，寇播州。至是李福为节度使，隆遣清平官董成至成都，移书于福。成与福抗礼，福囚之。上闻，有诏释成，召至京师，见便殿，遣还。咸通二年，遣兵陷安南。左仆射同平章事杜悰言：「西川兵弱，南诏强盛，未可轻绝。宜遣使祭吊，谕令改名，行册礼。帝肯之。会隆复寇嶲州，遂止。咸通三年，隆亲寇蜀，取万寿寺石佛归。时高真寺僧崇模有神术，从征。军中乏粮，又値岁暮，士卒思归，僧咒沙成米，咒水成酒，士卒各醉饱。一日僧化蝶回国乱宫，世隆妻以书达隆。隆答曰：妖若再来，令宫人于其衣背绣蝶。后僧复至，宫人绣之。隆见僧衣有蝶，令斩之。刑七次，首不殊。僧自云：用茅锯之乃断。果然。人见僧魂化一黑鹏飞去，盖僧本高真寺鹏巢中所得之儿也。咸通四年，寇西川。咸通五年，陷安南、邕管。咸通六年，陷嶲州。咸通七年，复攻安南。岭南西道节度使高骈救之，隆兵大败，骈遂定安南。咸通十年，隆遣使杨酋庆等入朝，谢释董成之囚。归成都俘三千人。定边节度使李师望杀其使，隆怒，率众攻蜀，陷嘉州。咸通十一年正月，陷黎州，入卭徕关，围雅州，击卭州，遂进攻成都。次眉州，西川节度使卢耽畏众寡不敌，通使请降。继而唐遣东川节度使颜庆复、大将宋威等率兵来战。世隆败屯星宿山，宋威戍沱江。隆迎战于毗桥，不胜，趋沱江，中伏。城中又出突将，夜火隆营，夺升仙梁。隆大败，奔双流江，无梁以渡，乃伪请和，三日梁成而济。咸通辛卯十二年，立鄯阐王宫。咸通壬辰十三年，于白崖诸葛武侯所立铁柱之地，铸天尊柱，高八尺。蔚昔年曾至铁柱宫，其地界白崖、弥渡、蒙化三境之间。其柱刻字云：建极十三年岁次壬辰四月朔庚子十四日癸丑建立。咸通十四年，攻黔中。又寇西川，作浮梁济大渡河，防河兵马使黄景复伏兵，半渡击败之。会隆国中新兵继至，接战，景复败走。隆进兵陷黎州，入卭徕关。遂遣王保诚等四十人谩书诣剑南节度使牛丛，欲假道入朝，请憩蜀王故殿。丛囚其使三十八人，释酇咙及段酋迁二人还。隆乃退兵至新津而旋。僖宗乙未乾符二年，攻雅州。西川节度使高骈追至大渡河，大败之，俘酋长五十人，收复黎州、卭徕关，斩黄景复以狥。乾符三年，遣使诣高骈请和，不许，斩使者一人。隆怒，自是唐使至不拜，惟拜和尚。骈知之，乃遣僧景仙往谕公主事，隆乃下拜定盟。禧宗丁酉乾符四年二月，复寇蜀，高骈御退之。骈又结吐蓄尚延心嗢、末鲁褥月等为间，筑戎川州、马湖沭沐源川、大渡河三城，列屯拒险，料壮卒为平夷军。世隆气夺，因恚发疽，卒于越嶲景净寺，在位十八年，子隆舜立。
|
|-
|}

===Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆舜，唐僖宗丁酉乾符四年卽位，年十七岁。明年，改元贞明，又改元嵯耶、承知、大同，改国号曰大封民国。遣使于唐请和，诏许之。自劝龙晟至世隆以来，侵蜀伐安南，用兵五十馀年，帑藏不给，横敛于民，上下倶困。舜立，耽于酒色，委政臣下，故愿求和于唐，乃遣段宝诣岭南节度使辛谠，请修好。谠奏，许之，以息边患。乾符六年，遣使于唐求和亲，无表，只用牒，称弟不称臣。唐帝召百官议，礼部侍郞崔澹曰：「南诏无礼，恐贻后笑。」使者上书与澹争。帝谕解之。议者谓中国多故，南诏寖强，不若权与和亲。便从之。僖宗庚子广明元年春正月，唐命宗正少卿李龟年来和亲。僖宗辛丑中和元年，上表款附。中和癸卯三年，唐以宗室女为安化长公主，妻隆舜，僖宗乙已光启元年，遣宰相赵隆眉、清平官杨奇鲲、段义宗三人，朝唐帝行在，且迎公主。高骈在淮阳飞章上言：「三人南诏心腹。宜止而酖之。」唐帝从其言。隆眉等死，南诏遂不复振矣。是年昆仑国进美女，舜嬖之。光启二年地震，龙首、龙尾二关、三阳城皆崩。昭宗己巳乾宁四年，隆舜多内嬖，常信谗以诛其下，淫虐日甚。竖臣杨登弑之于东京，在位二十年，子舜化贞立。
|
|-
|}

===Shunhuazhen舜化贞　　　　　伪谥孝哀帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|舜化贞，唐昭宗丁巳乾宁四年卽位，年二十一岁。明年，改元中兴。上书于唐，朝廷欲报之。利州刺史王建上言：「臣在西南，彼必不敢犯塞，小夷何足辱诏书。」遂止。昭宗光化二年，立五学敎主。十一月，诛杨登，族其家。光化庚申三年，铸崇圣寺丈六观音，清平官郑买嗣合十六国铜所铸，蜀人李嘉亭成像。一说唐天宝间，崇圣寺有僧募造丈六观音像，未就。夜忽雨，旦视之，铜也，卽取以铸像。像成，白光弥覆凡三日夜，至今人称为雨铜观音。唐昭宗壬戌天复二年，舜化贞卒，一说实郑买嗣弑之。，在位五年。化贞有一子，生甫八月，郑买嗣主国事，遂启贞妻曰：「母后深宫，群臣无主，臣当抱太子临朝。」贞妻是其言，以子付之。买嗣抱子出，潜手伤其阴，子哭不已，乃送回宫中。明日，子死。贞妻疑而诘之，买嗣怀不安，遽起兵杀蒙氏亲族八百人于五华楼下，遂簒立焉。
|
|-
|按：蒙氏南诏大蒙国，自细奴逻禅立，起唐太宗己酉贞观二十三年，讫昭宗壬戌天复二年，传十三世，共二百五十五年。
|
|-
|}

==Dachanghe Generations《大长和国　　传三世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dachanghe Generations《大长和国　　传三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|郑买嗣又名。　　　伪谥圣明文武威德桓皇帝。
|
|-
|郑买嗣，又名，唐巂州西泸令陷南诏臣蒙氏，为清平官郑回之七世孙。
隆舜时历官侍中，权势日重。隆舜巡幸无度，留买嗣守国，遂专政柄。舜化贞时为相，化贞卒，嗣贼杀其子，簒蒙国，于唐昭宗壬戌天复二年十二月卽位，年四十二岁，国号大长和，仍都大理。明年，建元安国。后梁太祖开平丁卯元年，建普明寺。开平三年，铸佛一万尊，送寺祈福，为杀蒙氏八百人故也。开平四年八月，买嗣卒，在位八年，子仁旻立。
|
|-
|}

===Renmin 　《仁旻　　　伪谥肃文太上皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|仁旻，后梁太祖庚午开平四年卽位，年二十二岁。明年，改元始元，又改元天瑞、景星、安和、贞佑、初历。末帝甲戌乾化三年，旻攻蜀。蜀高祖王建发兵拒之，旻兵大败，溺水使者万馀人。后唐庄宗癸未开同光元年，施宫寺灾，僧智照撰『封民三宝记』。同光二年旻以朱鬃白马求婚于南汉刘龑，龑以增城公主妻之。明宗丙戌天成元年八月，仁旻饵金丹，躁怒，常杀人，遂暴卒，在位十六年，子隆亶立。
|
|-
|}

===Longdan 　《隆亶　　伪谥恭惠帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆亶，后唐明宗丙戌天成元年卽位，年十二岁，明年，改元天应。明宗戊子天成三年，东川节度使杨乾贞入朝，弑隆亶而立赵善政，计亶在位二年。
|
|-
|按：郑氏大长和国，自买嗣簒位，起唐昭宗癸亥天复三年，讫后唐明宗戊子天成三年，传三世，共二十六年。
|
|-
|大天兴国一作兴源国。　　一世
|
|
|}

==Dayining Generations《大义宁国　　一世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Yang Qianzhen 《杨乾贞　　　伪谥肃恭帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|杨乾贞于后唐明宗己丑天成四年夺大天兴国赵善政之位，改国号曰大义宁国，建元兴圣，又改元大命。乾贞萂村人。今大理府宾川州所属地。母名弥彔，有美色，蒙隆舜私焉。有孕，适渔人杨氏，生乾贞，后又生诏。其父捕鱼，贞立船头，见水中有人龙衣冠冕，左右有凤鸟，白光拥护，乃呼父视之。父见是贞之影，大奇之。长仕郑氏，官至东川节度使。至是夺善政位而自立。贞在位，贪暴特甚，中外咸怨。后晋高祖丁酉天复二年，通海节度使段思平起兵讨之。贞遣弟杨诏等五人出拒。诏兵败，乾贞出奔。思平遂得位，寻赦其罪，废为僧。计贞在位八年。
|
|-
|}


==Dali Generations《大理国　　　传十四世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siping《太祖圣神文武皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|	段思平，其先武威郡北人，世为南诏蒙氏将。唐元宗辛卯天宝十载，及甲午天宝十三载，唐再伐云南，云南王蒙

阁逻凤命世子凤伽异、大军将段俭魏迎战于点苍山及西洱河，两败唐兵。以功升俭魏为清平官，赐名忠国，寻拜相，六传而至思平。其母因过江，水泛触浮木，若有感而娠，生思平，并其弟思良。思平为幕览，小府副将也。常游山中，得为帝之谶，又每多异徵。时东川节度使杨乾贞之弟杨诏者已贵，闻而忌之，使人贼思平。思平逃匿于崇恩寺，在大理府城南九里。捕者追至，见蛛网盈寺门，不入，故得脱。后积战功，使为通海节度使。后唐明宗己丑天成四年，杨乾贞夺赵善政之位。受诏之谮，常欲除思平。平卜于秀山神祠，就其舅爨判自匿。后晋高祖丙申天福元年，乾贞索捕思平甚急。会善政臣守高方，素与思平善，密遣人招思平。思平与其弟思良、军师董迦罗走就之。皆裂冠，变姓名，为猎者，牵一犬至品甸波大村今大理府云南县地。宿旅舍。舍有戟，生牛革裹之，是夜风起，戟忽洞革出。思平惊曰：「是何銛利？得非神戟乎！」问主人曰：「戟何为？」曰：「以防夜耳。」曰：「防夜莫若犬。」遂以犬易戟去。行至叶镜湖，湖在大理府云南县地得神马。饥取野桃而食，核上有虫啮「靑昔」二字，思平解为十二月二十一日，意其吉兆。于是急趋而前，借兵于东方黑爨三十七蛮部，会于石城，今曲靖府是。以董迦罗为军师。兵集之期，适十二月二十一日也。所向皆克，遂进攻大理，讨干贞。时诏等陈兵据桥，军不能过。思平夜忽得三梦：人无首；玉瓶无耳；镜破。觉而告其下。迦罗觧之曰：君乃丈夫，去首为天；玉瓶去耳为王；镜破则无对者，此神示吉兆。是日，有被缨浣沙妇，指渡处曰：「人从我江尾，马从三沙矣，尔国名大理。」从之，乃得过江，击诏等杀之。乾贞闻诏等军败，出奔。思平卽位，时天福丁酉二年也，年四十四岁。建号大理国，建元文德，仍都大理。天福三年封董迦罗为相国，封高方为岳侯，分治成纪、巨桥等地。封爨判为巴甸侯。祠秀山神，免东方三十七蛮部徭役，赦国中凡有罪无子孙者。天福四年，赦杨乾贞罪，废为僧。一说乾贞败后，挈其妻子奔永昌郡。思平遣兵追之，至万剑树，乾贞自缢而死。思平俘其妻子亲属。帝好佛，岁岁建寺，铸佛万尊。后晋出帝甲辰开运元年帝崩，在位八年，子思英立。
|
|-
|}

===Duan Siyin 　《文经皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siyin 　《文经皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思英，后晋出帝甲辰开运元年卽位，明年，为出帝开运二年，改元文经。帝母杨氏桂仙娘没而为神，屡著灵应，封为楡城宣惠圣国母。是年，帝叔思良争位，废帝为僧，法名宏修大师。在位一年，叔思良立。一说思英素不肖，思平在日，常欲废之，不果。迨卽位，愈淫戏无度，群臣废之，而立思良。
|
|-
|}

===Duan Siliang 　《圣慈文武皇帝　　太祖之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siliang 　《圣慈文武皇帝　　太祖之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思良，后晋出帝乙巳开运二年卽位，明年，改元至治。后周太祖壬子广顺二年，帝崩，在位七年，子思聪立。
|
|-
|}

===Duan Sicong 　《思聪　　伪谥至道广慈皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sicong 　《思聪　　伪谥至道广慈皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思聪，后周太祖壬子广顺二年卽位，明年改元明德，又改元广德。宋太祖乙巳开宝二年，思聪卒，在位十七年，子素顺立。
|
|-
|}

===Duan Susun 　《素顺》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Susun 　《素顺》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素顺，宋太祖乙巳开宝二年卽位。明年，改元明政。先是，宋太祖丁卯乾德五年春，王全斌平蜀，还京师，请取云南，负地图进。太祖鉴唐之祸，以玉斧画大渡河为界，曰：「此外非吾有也。」由是段氏得据南诏，相安无事。太宗乙酉雍煕二年，素顺卒，在位十六年，子素英立。
|
|-
|}

===Duan Suyung 　《素英　　　　伪谥昭明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suyung 　《素英　　　　伪谥昭明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素英，宋太祖乙酉雍煕二年卽位。明年，改元广明，又改元明应、明圣、明统、明治。太宗至道二年，述『传灯录』。真宗己酉大中祥符二年，素英卒，在位二十四年，子素廉立。
|
|-
|}

===Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素隆，宋真宗壬戌干兴元年卽位，明年改元明通。仁宗丙寅天圣四年素隆禅位为僧，在位四年。侄素贞真立。
|
|-
|}

===Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素真，宋仁宗丙寅天圣四年卽位，明年改元正治。仁宗辛巳庆历元年素真禅位为僧，在位十五年，孙素兴立。
|
|-
|}

===Duan Suxing 　《素兴　　　　伪谥天明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suxing 　《素兴　　　　伪谥天明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Lianyi　《廉义　　　伪谥上德皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Lianyi　《廉义　　　伪谥上德皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|廉义，宋神宗乙卯熈宁八年卽位。明年，改元上德。遣使入贡于宋。熈宁十年，又改元广安，作八龙王会。神宗庚申元丰三年，杨义贞杀廉义而自立。计义在位五年，自义贞弑其主廉义而自立，簒位仅四月，鄯阐侯高智升命子清平官高升泰起东方爨僰兵，讨而诛之，立廉义之侄寿辉。
|
|-
|}

===Duan Shouhai　《寿辉　　　伪谥上明皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}

===Duan Zhengming　《正明　　思廉之孙　　伪谥保定皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}
==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>9epgg3dguq26hppxsun67tryfafn1rt</sha1>
    </revision>
    <revision>
      <id>4669884</id>
      <parentid>4669883</parentid>
      <timestamp>2026-09-13T11:30:06Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Dali Generations《大理国　　　传十四世》 */</comment>
      <origin>4669884</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="72398" sha1="qh88uyopohwzd7gvtdgxy0pvm0z8cim" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Unofficial History of Nanzhao (南诏野史)
 | author   = Yang Shen (杨慎)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    =   
}}

== Front Matter ==

# [[Unofficial History of Nanzhao/Translator's Note|Translator's Note]]
# [[Unofficial History of Nanzhao/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Authorship 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|增订南诏野史上卷 明 四川新都杨愼升庵编辑
|
|-
|}

===The Title of Nanzhao 《南诏之称===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Title of Nanzhao 《南诏之称》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|蛮夷称王曰诏。先时滇有六诏，各据其地。六诏中蒙舍诏最强，后并吞五诏，故独称南诏。
|
|-
|六诏考六诏之地，东西四千里，南北二千九百里
|
|-
|蒙舍诏蒙细奴逻立国，居蒙舍川，地在永昌、姚州之间，处五诏之南。后奴逻曾孙皮逻阁并吞五诏，独称南诏。今蒙化厅是邆赕诏丰咩立国，居邓川。今大理府邓川州是施浪诏施望欠立国。居{{浪穹弥茨河蒙次和山，今大理府浪穹县是浪穹诏丰时立国，居浪穹。后其孙铎罗望迁剑川，改称剑浪诏。今丽江府属剑川州地是越析诏波冲立国。亦称摩诏。又号花马国。居嶲州。今丽江府是后，其兄之子于赠渡泸，邑于龙佉河蒙嶲诏嶲辅立国。居越嶲，今四川宁远府，越嶲厅是
|
|-
|}

===The Territorial Divisions of Nanzhao 《南诏分野》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Territorial Divisions of Nanzhao 《南诏分野》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|在天井鬼入参一度，汉书。次鹑首末位晋书。丽中台上位北斗开阳一星。宋书。在地乃梁州裔土，蜀之苑囿。河图纬。
|
|-
|}

===The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周鄯阐国、白崖国、昆弥国。战国时滇国，汉西南夷、益州、白子国。后汉建宁国。晋、宋、齐、梁、陈，宁州。隋昆州。唐初，南宁、六诏，唐文宗太和间，名鄯阐府。宋仍名南诏。元名中庆。明名云南省。
|
|-
|	国朝因之。按：汉武帝元狩元年，彩云见南中，在今大理府赵州之白崖。云南之名始此。唐元宗间问蒙舍诏盛逻皮之相张建一作俭成住何处？曰：「南边云下。」因命为云南。又元宗见祥云起，名祥州。今大理府之云南县也。
|
|-
|}

=== General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|鄯阐国蒙苴颂，昆弥国庄蹻、仁果、龙佑那据于周、秦、汉迄六朝。细奴逻据于唐。郑买嗣、赵善政、杨于贞、段思平、高升泰曁正湻，相继据于唐末迄
南宋。凡历有九姓，而雍闓、孟获不与焉。段氏与南宋理宗壬子湻佑十三年为蒙古所灭，而段实于理宗景定二年袭总管，传十二世，明太祖壬戌洪武十五年平云南，擒段世，并段段明之二子苴仁、苴义。赐苴仁官雁门卫镇抚，苴义官武昌卫镇抚，段氏之世土方绝，而又别封其族人段保为大理府云龙州土知州。国朝尚有袭土职者。
|
|-
|}

=== Titles and Official System of Nanzhao《南诏称谓官制》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Titles and Official System of Nanzhao《南诏称谓官制》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|南诏称帝曰骠信，王曰诏，自称曰元，称后曰信么，亦曰九么，妃曰进武，兄曰容，弟曰钟，下曰昶。其设官则有把国事八人，曰坦绰，曰布燮，曰九赞，谓之清平官。曰酋望，曰正酋望，曰员外酋望，曰大（将军）〔军将〕，曰员外。又设九爽之名，爽，省也。功爽主官人，宗爽主户籍，万爽主财用，慈爽主礼，引爽主宾客，幕爽主兵，罚爽主刑，厥爽主工作，禾爽主商贾，皆清平官、酋望、大军将兼之。以清平官子弟为羽仪长八人，清平官见王不得佩剑，惟羽仪长佩之。又有六曹长二人，曹长有功升大军将，凡十二人。又立三托：巨托主仓廪，气托主马，禄托主牛。大府主将曰演习，副曰演览；中府主将曰缮裔，副曰缮览；下府主将曰澹酋，副曰澹览；小府王将日幕撝，副曰幕览。每府有陀酋，陀酋卽掌书记判官之类。外有八节度使：日弄栋节度使，今楚雄府姚州。曰银生节度使，今景东厅及鎭沅州地是。曰永昌节度使，今永昌府是。曰丽水节度使，今丽江府是。曰剑川节度使，今丽江府剑川州是。曰东川节度使，今东川府府是。曰通海节度使，今临安府通海县是。曰拓东节度使。今云南府昆阳州北平定乡，蒙氏子凤伽异曾筑城于此地。又有二都督：曰会川都督，今四川宁远府会理州地是。曰通海都督。又设十睑，蛮语谓州为睑。苴音斜。羊睑，又名羊睑，卽今大理府太和县。赵州睑，今大理府赵州。白崖睑，又名勃弄睑，今赵州之白崖。，云南睑，今大理府云南县。蒙舍睑，今蒙化厅。大厘睑，又名史睑，今太和县喜州。邆川睑，今大理府邓川州。品澹睑，蒙秦睑，矣和睑。三睑未详其地。○蔚按：别本十睑中苴羊睑、赵州睑、白崖睑而下，作义督睑，今剑川州；威远睑，今普洱府威远厅南；河东睑，末详其地；越睑，今永昌府腾越州；北方睑，又名成偈睑，今永北厅；楼头睑，今四川叙永厅，属永宁县；路睑，今楚雄府广通县；与云南睑以下七睑异。○按：又考此七睑中，其越睑、北方睑、楼头睑、路睑凡四睑，见于『汉地里志』及『唐书?南蛮传』中，睑并作赕，音闪，字旣不同，音又各异，似非列于十睑之数。凡人丁壮者皆为战卒。王之亲兵曰朱弩佉苴，音蛆。按：元微之白乐天乐府皆作佉嗟，未审孰是。佉苴，韦带也。每兵百人置罗苴子统一人，戴朱鞮鍪，负犀革铜盾而跣足。自大军将以至曹长，皆系金佉苴尚绛紫，有功加锦，又有功加金波罗。卽虎皮。民兵号白衣，凡民兵出以望苴蛮为先驱。
|
|-
|}

===Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|因远部。威远睑治，其地总名和泥，今元江府是。休腊部。今临安府河西县。嶍峨部。今临安府嶍峨县。屈中部。今临安府阿迷州。溪处甸部、伴溪落恐部。今倶为长官司，属临安府。铁容甸部。今为亏容长官司。官桂思陀部。今为思陀甸长官司，皆属临安府。王弄部、强现三部。今属开化府。师宗部。今广西州师安县。弥勒部。今广西州弥勒县。吉输部、袖恶部。倶在弥勒县地。维摩部。卽广西府维摩州。州裁，今属广西州地。罗雄部。今曲靖府罗平州。纳垢州。今曲靖府马龙州。落温部。今曲靖府陆凉州。磨弥部。今曲靖府沾益州。仁德部。今曲靖府寻甸州。夜苴部卽曲靖府亦佐县，县裁，今归罗平州。强宗部。卽澄江府阳宗县，县裁，今归河阳县。步雄部。今澄江府江川县。罗伽部。卽步雄部分地。休制部。今澄江府新兴州。落蒙州。今澄江府路南州。弥沙部、邑市部。皆落蒙部子孙分治之。阳城堡部。今云南府晋宁州。罗部。今云南府罗次县。乾矢部、罗婺部。倶在武定府曲州，州裁，今属武定州。华竹部。今武定州元谋县。洪农碌券部。今武定州禄劝县。掌鸠法块部在禄劝县城东五里。○以上三十五部在迤东地。白鹿部。今楚雄府。谋统部。今丽江府鹤庆州。○以上二部在迤西地。
|
|-
|}

==Nanzhao through the Generations《南诏历代》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Nanzhao through the Generations《南诏历代》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|白古记：西天天竺摩竭国阿育王骠苴音斜。低娶欠蒙亏为妻，生低蒙苴。苴生九子，长子蒙苴，附罗十六国之祖；次子蒙苴廉，吐蕃之祖；三子蒙苴诺，汉人之祖；四子蒙苴酬，东蛮之祖；五子蒙苴笃，生十二子，七圣五贤，蒙氏之祖；六子蒙苴托，狮子国之祖；七子蒙苴林，交趾国之祖；八子蒙苴颂，白子国仁果之祖；九子蒙苴閦初六切。白夷之祖。○『哀牢今永昌府。夷传』：哀牢蛮蒙伽独捕鱼易罗池在永昌府城南。溺死。其妻沙壹一作壶。往哭之水边，触一浮木，有感而妊，产十子。后携子至池上，木化为龙，人言曰：「我子安在？」九子惊走，独季子背龙而坐，龙舐其背。蛮语谓背为九，坐为隆，故名之曰九隆氏。哀牢山一名天井山，在永昌府。下有妇名奴波息，生十女，九隆弟兄娶之，立为十姓：董、洪、段、施、何、王、张、杨、李、赵，皆刻画其身象龙文，于衣后著尾。子孙繁衍，居九龙山山在永昌府城南。溪谷间，分九十九部，而南诏出焉。
|
|-
|}

===Shanchan Guo《鄯阐国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shanchan Guo《鄯阐国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周时立国，年代久远，其姓名世次莫考。
|
|-
|}

===Baiya Guo《白崖国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baiya Guo《白崖国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|西天天竺摩竭国阿育王低蒙苴第八子，蒙苴颂居白崖，因地名，号白崖国，传世莫考。后昆弥氏继之，号昆弥国。
|
|-
|昆弥国一名拜国。
|
|-
|昆弥氏，传世姓名莫考。战国时，楚将庄蹻据滇，并有其地，号滇国。
|
|-
|}

===Dian Guo《滇国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dian Guo《滇国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|战国时，楚顷襄王命将庄蹻范蔚宗后汉书作庄豪。将兵循江上，略巴、蜀、黔中以西，蹻至以兵威畧定滇地属楚。欲归报，会秦司马错攻楚，黔中道塞。蹻遂以其众王滇，号滇国，踞之。后有王常羌者好佛，国势不振。法令不行，国人遂推白崖国蒙苴颂之后，白饭王之裔仁果为王，治白崖，于是两国角立。后仁果奉汉，封为白子国。
|
|-
|}

===Baizi Guo《白子国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baizi Guo《白子国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|汉武帝通西南夷，遣使至滇，求身毒国。滇王常羌问使者曰：「汉孰与我大？」使者还报，武帝怒其言不逊。时白崖国蒙苴颂之后，天竺国白饭王之裔仁果者，为众所推立于白崖。武帝乃册封仁果为王，号白子国。后迁于澄江，今澄江府。迨龙佑那继之，号建宁国。○又一说：白子国之先，有阿育国，王能乘云，上天娶天女，生三子，长季二子封于金马、碧鸡，独封仲子于苍洱之间，崇奉佛敎，不茹晕，日食白饭，人因称为白饭王。迨后有仁果者，汉封为滇王，号白子国。又十五世至龙佑那，后汉诸葛武侯南征，次白崖，以佑那为酋长，赐姓张氏，仍统其民，号建宁国。
|
|-
|}

===Jianning Guo《建宁国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|后汉后皇帝乙巳建兴三年，益州耆帅雍闓，假鬼术杀建宁太守王昂，归东吴，吴王孙权以闓为永昌守。后汉诸葛武侯南征，至白崖，杀雍闓，擒孟获，乃封白子国王仁果十五世孙龙佑那为酋长，赐姓张氏，于白崖筑建宁城，蔚按建宁城废址在今大理府赵州之弥渡。号建宁国，立铁柱蔚按：今弥渡有铁柱宫，铁柱尚存。先为建宁国王张乐进求甫铸，后南诏蒙世隆复重铸，名曰天尊柱，高八尺。并『南中纪功碑』，铭其背曰：「万岁之后胜我者过此」。迨至隋时，行军总管太平公史万岁征南宁夷爨玩，西破三十馀部，至此，见其碑铭，命左右踣之。其碑跌，中复有志曰：「史万岁不应踣吾碑」。万岁惊异，复树碑，祭拜而去。后张龙佑那仍迁国澄江，传三十二世至十七世孙张乐进求，唐太宗己酉贞观二十三年封为首领大将军。后见蒙舍川蒙细奴罗有奇相，遂妻以女，逊国与之。奴罗自称奇嘉王，建号大蒙国，又称南诏。
|
|-
|}

==Nanzhao《南诏国》==
===13 Generations of Nanzhao 《南诏大蒙国传十三世》 ===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ 13 Generations of Nanzhao 《南诏大蒙国传十三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|细奴一作农。逻一作罗。　伪谥高祖奇嘉王
|
|-
|细奴逻，又名独罗消，西天天竺摩竭国阿育王低蒙苴第五子蒙苴笃之三十六世孙。生有奇相。唐太宗贞观初，其父舍龙尨，又名龙伽独，将奴逻自哀牢避难至蒙舍川，耕于巍山。今蒙化厅之巍宝山。一日，有老僧，美髯，冠赤莲冠，披袈裟，持钵至奴逻家乞食。时奴逻与子逻盛炎方耕巍山之下，其姑与妇将往饁。见僧乞食，遂食之。再炊往饁，僧坐不去。姑妇持饷中道，僧已在彼，复乞食，姑妇又食之。返而复炊，持饁至巍山，则见僧坐盘石上，前有靑牛，左白象，右白马，上覆云气。云中二童子，一执铁杖于左，一执方金镜于右。姑妇惊喜，复以所饷供之。僧问何所愿？姑妇不知对。僧曰：「奕叶相承」。及趣奴逻等至，则但见一人持钵，坐五色云中，而盘石上惟馀衣痕及牛象马之迹耳。奴逻素有祥异，会唐封首领大将军建宁国王张乐进求，以诸葛武侯所立白崖铁柱，岁久剥蚀重铸之。因社会祭柱，柱顶故有金镂鸟，忽能飞，集奴逻左肩，相诫勿动，八日乃去。众骇异，谓天意有属。进求遂妻以女，举国逊之。于唐太宗己酉，贞观二十三年卽位，年三十二岁，建号大蒙国，称奇嘉王，据南诏。高宗庚戌永徽元年，建都蒙舍川，于巃｛山＋于｝山在今蒙化厅西北三十五里。筑巃山＋于城。永徽癸丑四年，遣逻盛炎入朝唐，诏授奴逻为巍州今蒙化厅刺史，赐以锦袍。大勃弄今大理府赵州白崖。酋杨承顚寇麻州，在今曲靖府马龙州城北里许。唐命郞州唐贞观初，分牂牁郡北界置郞州，后改名播州，卽今贵州遵义府。又有郞州，在今云南县地。道行军总管赵孝祖讨之。孝祖先入小勃弄，今云南县地。酋长没盛迎战，孝祖斩之。进至大勃弄，攻其城，破之，擒杨承顚，改云南县为匡州，领勃弄、匡州二县。高宗显庆二年，凤鸣于浪穹罗浮山，乃改名为凤羽山，在大理府浪穹县西南三十里，又名鸟吊山。见『水经注』。封十二圣贤为十二山神。时澄江人波罗旁有经济才，用为文臣；郭郡矣素以勇略闻，用为武臣。又有杨波远者，相传为东汉时人，常骑三角靑牛，号神明大士，能知盐泉，滇中盐泉多为波远所开创。奴逻在位，遵唐正朔。高宗甲戌上元元年，奴逻卒，在位二十六年，子逻盛炎立。
|
|-
|逻盛炎又名逻晟。伪谥世宗兴宗王。
|
|-
|	逻盛炎。唐高宗甲戌上元元年卽位，年四十岁，以张建成为相。明年，盛炎临朝，元宗壬子先天元年，姚州蛮叛归吐蕃。唐命御史李知古讨之，筑城立州县。知古诛豪杰，掠子女，蛮怨，引土蕃，攻杀知古，于姚嶲路绝，而盛炎独奉唐正朔。是年，盛炎卒，在位三十九年，子盛逻皮立。
|
|-
|}


===Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|盛逻皮，唐元宗壬子先天元年卽位，年四十岁。明年为元宗癸丑开元元年，唐授逻皮为特进，封台登郡王今四川宁远府冕宁县地。设官征商税。开元二年，遣张建成入朝于唐。立土主庙。开元九年，皮叛唐。开元十四年，立庙祀晋右将军王羲之为圣人。元宗戊辰开元十六年，逻皮卒，在位十六年，子皮逻阁立。
|
|-
|皮逻一作罗阁石刻作归义王魁乐觉封云南王。
|
|-
|皮逻阁，唐元宗戊辰开元十六年卽位，年三十一岁。开元十八年，灭五诏，自称南诏王。先是，蒙氏恐三十七蛮部不服，选亲族为五诏。未几五诏抗命，逻阁遂赂剑南节度使王昱，求合六诏为一。昱奏于朝，许之。逻阁乃豫建松明大楼，祀祖于上。使人谕五诏曰：「六月二十四日乃星回节蔚按『大理郡志』汉元封间，叶楡妇阿南者为酋长，曼阿娜之妻。娜为汉将郭世忠所杀，欲妻南。南曰：能从三事，当许汝一作幕次祭故夫；一焚故夫衣，易君新衣；一令国人皆知我以礼嫁。忠如其言。明日，聚国人张松幕祭其夫。下置火，南藏刃出，俟火炽焚夫衣，卽引刀刃自断其颈，仆火中，时六月二十五日也。国人哀之，故岁以是日燃炬吊之，名为星回节云。是又当为二十五日。当祭祖，不赴者罪。」四诏听命。惟越析诏波冲之兄子于赠，远不赴会，而邆赕诏丰哶孙｛辵＋皮｝逻邆之妻慈善者，止逻邆勿赴。邆不听。慈善不得已，以铁钏穿于邆臂而行。二十四日，逻邆及施浪诏施望欠弟施望千、浪穹诏丰时孙锋罗望、蒙嶲诏嶲辅子罗原皆至逻阁所。逻阁偕登楼祭祖，祭后享胙食生饮酒，迨晚，四诏尽醉。逻阁独下楼，焚钱遽纵火，火发，兵围之，四诏皆焚死。逻阁遣使至四诏所，报焚钱失火，四诏被焚，状令各诏收骨。四诏妻至，莫辨其骨。独慈善因铁钏得焉，携归葬之。逻阁旣灭四诏，取各诏宫人，念慈善慧而甚美，遣兵围其城，迫取之。慈善曰：「吾岂忘夫事仇者？」闭城坚守，半月城中食尽，慈善度不能支，卽自杀，时七月二十三日也。逻阁嘉其节，乃封赠为宁北妃，并旌其城曰德源城。城废址在今大理府邓川州城东北二里许。开元戊寅二十六年，逻阁破吐蕃及弥蛮，入朝，元宗礼之，加封为特进，云南王，越国公，开府仪同三司，赐名归义，并锦袍金钿带七事。王归国，以兵逐洱河蛮，筑太和城，今大理府城南十五里太和村地是。又筑大厘城今大理府城北四十里喜州是。守之，尽有云南之地。唐授王子阁逻凤右领军卫大将军兼阳瓜州刺史。开元二十七年，明矫叛，破剑川、浪穹、永昌。开元二十八年，王讨朋矫，平之。开元辛已二十九年，王自蒙舍川迁居太和城，立龙首、卽今上关。龙尾卽今下关。二关。唐加阁逻凤为左领军卫大将军。元宗癸未天宝二年，筑羊苴哶城于太和城之北。卽今大理府城。唐迁阁逻凤为左金吾卫大将军，寻拜特进都知兵马大将军。天宝甲申三载，西方进狮子皮。唐加阁逻凤为上柱国。天宝乙酉四载十月，城永昌。天宝丙戌五载，王遣孙凤伽异入唐，唐授伽异为鸿胪少卿，妻以宗室女，赐龟兹乐一部，元宗戊子天宝七载，王卒，在位二十年，子阁逻凤立。
|
|-
|阁罗凤一作觉乐凤。按：『德化碑』云：「家居阁罗凤」，则是取地名以为名也。袭封云南王，伪谥神武王。始建元。
|
|-
|	

阁罗凤，唐元宗天宝戊子七载卽位，年三十六岁。唐遣中使黎敬义持节册凤袭封云南王，敕置阳瓜州于蒙舍川，加授

凤伽异为上卿兼阳瓜州刺史，都知兵马大将军。天宝庚寅九载，王率妻子往谒都督李宓，过云南，太守张虔陀私之，又多徵求。王表虔陀之罪，中官贾奇俊抑之，不得达。王复遣将军杨罗顚等连表控告。元宗仍不省。凤怒，遣大将军王毗双、罗时等发兵攻虔陀。虔陀饮鸩死；遂取姚州，并夷州三十二。获唐嶲州西泸令郑回以归，爱其才，用为清平官。天宝辛卯十载，唐命剑南节度使鲜于仲通将兵八万征云南。凤赴泸南在楚雄府姚州之城北一百五十里。谢罪，愿还所俘掠，请罢兵。仲通不许，分三道而进。仲通自南溪路，大将李晖自会同路，都督王知进自步头路。今临安府地。凤就安宁，再伸衷悃。仲通不听，兵至曲州、靖州。二州今为曲靖府地。凤复遣首领杨子芬、参军江如之赍状，言若不罢兵，卽当归吐蕃，恐云南非唐有。仲通终不许，囚其使，进薄白崖城。别遣大将王天运统师绕出点苍山后。凤遣

凤伽异及大军将段俭魏迎山后师，自逆战于西洱河。唐兵大败，死者六万人，王天运战殁，仲通仅以身免。凤乃叛唐，建元长寿。遣弟阁陂和尚及子铎传、酋望赵佺邓、杨传磨侔等，并子弟六十人献凯吐蕃。陂有神术，人马往来吐蕃，不过朝夕之顷。天宝十一载正月一日，遣宰相倚祥叶乐持金冠、锦袍、金宝带、金帐状、安扛伞鞍、银兽器皿、珂贝、珠毯、衣服、駞马、牛鞻等物至邓川，以凤为兄弟之国，册为赞普钟南国大诏，给金印，称东帝。并授凤伽异大瑟瑟告身，都知兵马大将。凤遂改是年为赞普钟元年。发人口百户于浪穹，筑白崖睑城，又遣兵攻掠安宁。天宝甲午十三载六月，唐命前云南郡都督兼侍御史剑南留后李宓、广府节度使何履光等，率十道兵再征云南。兵逼邓川，凤遣凤伽异、段俭魏迎战于江口。时神川都知兵马使论绮里徐救兵已至巴蹻山，遂诱宓深入，内外夹击。宓粮尽，士卒饥疲，引还。凤以精兵追战，唐全军覆没，李宓被执，沉江死，何履光遁去。凤因进取嶲州会同郡，据清溪关，以破越析。此二役也，皆凤弟阁陂和尚及凤妃白氏行妖术，展帕拍手而笑，韩陀僧用钵法，以故唐兵再败。时唐先后丧师已二十馀万，凤乃敛战胔，筑京观于龙尾关河尾，名万人冢，立碑大书「唐天宝战亡士卒之墓」。而唐宰相杨国忠更揜败以捷闻，叙战功。令清平官郑回撰『德化碑』，唐流寓御史杜光庭书。立石太和国门外，明其不得已叛唐归吐蕃之故。天宝乙未十四载冬十一月，东平郡王安禄山反于范阳，凤乘机以兵取蜀卭州，筑卭子城，及丽水金宝城。升段俭魏为清平官，赐名忠国，旋拜相国。代宗甲辰广德二年，羊苴哶城成，凤名之曰大理城，又名紫城。代宗乙巳永泰元年凤伽异筑云南城卽今云南府省城。又筑拓东城，今云南府昆阳州北平定乡。遂以兵攻陷曲靖。代宗丁已大历十二年，永昌牛生三角，羊生四角，鸡九足，井有光。建观音寺于白崖。先是，逻盛炎时，相国张建成欲于白崖建寺，卜之吉。又地下有三戳观音，上截在西，中截在东，下截在东南。因盛炎旋卒，不果建。至是建寺，掘之果然。代宗戊午大历十三年，阁罗凤卒，在位三十年。因子凤伽异先死，后追谥悼惠王。孙异牟寻立。
|
|-
|异牟寻改国号曰大理国。封云南王，又封南诏王　伪赠廪孝桓王
|
|-
|异牟寻，唐代宗戊午大历十三年卽位，年二十四岁。明年改元见龙，又改上元，率兵三万取蜀为东府，又连土番入寇。唐命神策都将李晟击破之。师还，自称南诏王。德宗甲子兴元元年，牟寻迁居史城，卽大厘城。改号大理国，自称日东王。封岳读，以叶楡今大理府。点苍山为中岳，乌蛮今东川府。乌龙山一名绛云弄山，在今禄劝县东北三百里。为东岳，银生府今景东厅。蒙乐山一名无量山，在厅北九十里。为南岳，又封南安州今楚雄府属。神石亦为南岳，越赕今永昌府腾越州。高黎贡山一名昆仑隅，在腾越、潞江之间。为西岳，嶲州今丽江府是。雪山一名玉龙山，在府西北二十里。为北岳。封金沙江源出吐蓄旄牛徼外犂牛石下，本名犂牛河，又名犂水，讹为丽水。经丽江府、鹤庆州、姚州而东北达于四川马湖府之马湖，卽『山海经』所谓若水。『水经注』云：若水经云南之遂久县，卽今金沙江巡检司地。昔黄帝长子昌意德劣，不足绍承天位，降居斯水为诸侯，娶蜀山氏女，生颛顼于若水之阳，疑卽其地也。祀在武定州，兰沧江源出吐蕃鹿石山下，本名鹿沧，又名兰沧。兰沧讹为浪沧。自丽江府度云龙州至永昌府，东经顺宁府，达于车里，过交趾地而入于南海。祀在丽江府，黑惠江在顺宁府之东入狼沧江，而达于南海。祀在顺宁府，怒江源出西域雍望，奔流而下，深不可测。夏月多瘴，经怒夷地入丽江府境野人界。至永昌府境，乃名潞江。祀在水昌府，为四渎，各建神祠。又立三皇庙。德宗丙寅贞元二年，设官立九爽三托。考疆域，其地东至于铜柱、铁桥、蟠桃、玉楡，东南至于交趾国，南至于骠国，西南至于木落山，西至于太石，西北至于吐蕃，北至于神川，东北至于黔巫。八分之地，属以八演，皆中国降人为之经画者。贞元丁卯三年，寻居大理城。命子弟师事郑回。时寻苦吐蕃徵求无厌，会李泌劝德宗招云南以断吐蕃右臂。帝从之，命韦皋为西川节度使，皋受命招抚群蛮。郑回因说寻归唐，寻以为然。皋遣谍者致书于寻，吐蕃知而疑之，乃责南诏大臣为质。寻愈怨。于是，决计归唐。皋以闻，德宗乃命皋作书谕寻。是年四月，吐番破蜀，来征兵，蔚按：卽吐蕃劫浑瑊清水盟之岁。寻谢绝之。贞元五年，寻遣乌蛮勿邓大鬼主苴梦冲、两林都大鬼主直那时聘于皋，因入朝。皋遣其属崔佐时报之。时吐蕃使数十人先在，佐时至，寻令更衣入。佐时不可，曰：「天朝大使。岂衣夷衣？」寻不得已，夜迎之。佐时至，大宣诏旨，令寻斩番使，去其所立之号。寻遂与佐时盟于点苍山下。贞元九年，寻遣使上表，请从韦皋袭吐蕃。诏册封为云南王，以韦皋为云南安抚使。王遣使诣皋，献夷中歌。贞元十年，吐蕃徵兵于王，王阳示寡弱，以兵三千应之，自将数万人踵其后。正月，袭吐蕃，战于神州，断铁桥，在巨津废州，今丽江府西北地。取十六城，俘其五王，降众十馀万，获军资甲仗无算。遂遣弟凑罗栋、清平官尹仇宽献捷于唐，并献地图、纳贡及吐蕃所给金印，请复号南诏。于是，唐以祠部郞中袁滋为中丞，赐金紫充册使。赐王银窠金印，印文曰：「贞元册南诏印」。王北面跪受。宴使者，出元宗天宝五载所赐王父凤伽异银跳脱马头盘数物，并指老笛工、歌女曰：「皇帝所赐龟兹乐，惟二人在耳！」使者日：「南诏世荷唐恩，当深思祖考子孙勿替，尽忠皇唐。」王对曰：「敢不敬使者之命。」随遣清平官尹辅首入谢，献铎鞘、郁刀、生金、瑟瑟、牛黄、氎、纺丝、越赕绕伦马。蔚按：铎鞘，疑当作择矟，状如残月，有孔旁达，出丽水，饰以金，月祭之血，所击无不洞。段柯古『酉阳杂俎』云：南蛮有毒槊无刀刃，状如朽铁，中人无血立死。言自天而下，入地丈馀，祭地乃掘得之，云云。疑卽铎矟，毒为铎字之讹，槊字本同矟宇也。郁刀铸时以毒药并冶，取莹耀如星者，凡十年乃成，淬以马血，镂金犀饰镡首，伤人卽死。因浪人所铸，又名浪剑，夷中甚宝之。七月，又攻吐蕃，并破施蛮、顺蛮，施蛮、顺蛮卽施浪、浪穹二诏之后，自南诏并吞五诏，五诏之后不复称诏，止称蛮。俘其王置白崖城。贞元十二年，取越赕，置软化城。贞元十四年，请以大臣子弟质于朝，韦皋却之。固请，乃尽舍成都，遣就学。贞元十五年，王开白国北方赕地，今永北厅。徙弥河白蛮及罗落摩蛮实之，号剑羌。是年，王从韦皋再败吐蕃于铁桥。初，王谋击吐蕃，以邆川、卽今邓川州。宁北卽今浪穹县。等城当寇冲，乃峭山深堑，修战备。至是吐蕃谋袭南诏，王告于皋，遣将屯黎州、嶲州以应之。吐蕃引兵攻嶲州，皋严兵以守，别遣将袭击，降其帅，吐蕃惧，退至铁桥。王令人毒其水，吐蕃人马多死，退屯三泸水，王与皋部将杜毗罗击败之。贞元十六年，王率子寻阁劝入朝于唐，召对延英殿，进奉圣乐舞，德宗御麟德殿观之。贞元十七年，王夜绝泸水，斩吐蕃屯卒，又合鬼主破之于泸西。吐蕃大惧，欲悉师收嶲州，以绝南诏。王谓韦皋曰：「吐蕃声取嶲州，实窥云南，请进军羊苴咩城。」皋督诸将分道与王会，陈兵深入，拔木波城。前后凡克城七，焚堡百五十所，斩获无算，生擒论莽热，献于唐，并进铠甲十五万。皋班师，帝遣中使慰抚王。王自是比年贡方物，唐帝深礼之焉。贞元十九年，王封云南金马碧鸡二山之神为景帝，建妙音寺塔，筑大理雪峰长城。宪宗戊子元和三年七月，王卒。唐遣使祭吊，在位三十年，子寻阁劝立。
|
|-
|寻阁一作觉劝又名新觉劝。　袭封南诏王　伪谥孝惠王
|
|-
|寻阁劝，唐宪宗戊子元和三年卽位，年三十一岁。唐册劝袭封南诏王，赐元和金印。宪宗己丑元和四年正月，改元应道，群臣上尊号曰骠信，以鄯阐为东京，大理为西京，重修曲靖崇真寺。寺为晋代所建。十一月王卒，在位一年。子劝龙晟立。
|
|-
|}

===Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝龙晟，唐宪宗己丑元和四年卽位，年十二岁。唐册袭封南诏王。明年，改元龙兴。铸佛三尊，送佛顶峰寺，用金三千两。元和九年，晨寇嘉定州，有飞天神兵破之。先是，节度使杜元颖守成都时，时滇兵至嘉定之沐源州，忽自惊溃。蜀军获一夷卒问之，云适见遍山神兵，一神将长斧坐二鬼上，声若迅雷，故尔惊走。至是神复现形，自后追杀，卽时死酋长二人。盖嘉定向有飞天神庙，两破滇兵者，皆此神也。宪宗丙申元和十一年，晟淫虐失道，弄栋节度使王嵯巅弑之，时年仅十九岁，唐命少监李铣祭吊，在位七年，弟劝利立。
|
|-
|}

===Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝利，唐宪宗丙申元和十一年卽位，年十五岁。唐册袭封南诏王。王嵯巅东寇。明年，改元全义。元和十三年，厚赏王嵯巅，赐姓蒙，封太容。元和十四年，废王嵯巅，赦其罪，命敬信三宝，为清平官。元和十五年，又改元大丰。重修崇圣寺。五月，大雨霖，龙首、龙尾二关倾。除洱河水怪，建龙屋塔。高十二丈。按：『白古记』：唐时洱河有妖蛇，名薄劫，兴大水淹城。蒙国王出示：有能灭之者，赏半官库，子孙世免差徭。部民有段赤城者愿灭蛇，缚刃人水，蛇吞之，人与蛇皆死，水患息。王令人剖蛇腹，取赤城骨葬之，建塔其上，毁蛇骨灰塔，名为灵塔。在今大理府城南龙尾关内点苍山马耳峰下羊皮村。每年有蛇党起风来剥塔灰。时有谣曰：赤城卖硬土。今『龙王庙碑』云：洱河龙王段赤城云。永昌生两头牛。穆宗甲辰长庆四年，赐南诏王金印。是年王卒于东京，在位八年，弟丰佑立。丰佑慕中国之风，独不肯连父名。丰佑石刻作劝丰佑　　册封滇王　　伪谥昭成王
|
|-
|	

丰佑，唐穆宗甲辰长庆四年卽位，年七岁。唐遣京兆少尹韦审规持节册封为滇王。王遣洪成酋等人谢。明年，改元保合，又改元天启。西僧赞陀啒哆建鹤庆元化寺。先是，鹤庆地水淹，僧杖刺东隅泄之。水中得樟木，刻为佛，咒之忽灵，远近名曰活佛。按：活佛，后至明成化间，福建莆田林俊为云南宪副闻之，亲至寺中，将佛火之，得金数百两入官，又毁他寺三百，人呼为林劈佛。建常平仓，筑邓川城。敬宗乙巳宝历元年，重修大理崇圣寺一名三塔寺。成先是，王嵯巅广寺基方七里。圣僧李成眉贤者建立三塔，高三十丈。佛一万一千四百，屋八百九十，铜四万五百九十筋。元和十五年经始，至是工竣。塔顶旧有铁柱款识云：「贞观六年尉迟敬德监造」，盖寺之建久矣。重修云南东寺塔，高百五十尺，西寺塔高八十尺，二寺亦贞观间将作大匠尉迟敬德所建。文宗丁未太和元年，王母出家，法名惠海。太和二年，用银五千，铸佛一堂，废道敎。太和己酉三年，僧梦岛造永昌卧佛，长丈六。六月朔，星落如雨。命王嵯巅等寇蜀。先是，西川节度使杜元颖失士卒心，军逃入南诏，因此知蜀虚实。佑遂遣嵯巅等攻蜀，陷嶲、戎、卭三州，攻成都，止西郛十日，掠经书、宝货、子女无算，蜀中残敝。并寇梓州、蜀州。佑上表于唐，请诛元颖。唐改云南为鄯阐府。卽今云南府省城。太和四年，唐贬杜元颖循州司马，以义成节度使李德裕为西川节度使。裕至西川，建筹边楼，日召习边事者访问，凡山川险要，南道与蛮相入者图之左，西道与吐蕃相接者图之右，不啻身尝经历焉。乃奏请留北兵以重镇守，修甲胄、备器械。率户二百取一人习战，作雄边子弟等十一军。筑仗义、御侮、柔远诸城以扼要害，复卭崃关，徙嶲州治台登，以夺蛮险。令转卭、雅粟以十月而运，先夏而至，人不苦瘴，边境始安。至是使人于佑，责归所俘。太和五年五月，佑归所俘西川四千人于德裕。太和六年，佑掠骠国民三千，徙之拓东城。武宗乙丑会昌元年，佑遣军将晟君筑横渠道自磨用江至于鹤拓，灌东皋及城阳田，与龙佉江合流入于河，谓之锦浪江。又潴点苍山玉局峰顶之南为池，谓之高河，又名冯河。更导山泉共泄流为川，灌田数万顷，民得耕种之利。会昌六年九月，佑攻陷安南，经略使裴元裕死之。宣宗丁卯大宗元年，佑妃卒，佑郁郁不乐，臣下请选妃女备后宫。得罗部今云南府罗次县。一美女进之，有宠。女好佛，建罗次寺，至今灵异。六月大旱，佑令僧寿海祈雨。僧曰：「昔汤旱七年，六事自责，天雨七日。今王酒色妄杀，天怒不雨。王如改悔，天雨自至，何以祈为？」佑如僧言，自责自改，数日果雨。佑女至崇圣寺进香，回至城西，为一乘白马人摄去，寻之不得。佑告于西僧赞陀啒哆，哆曰此山神也。乃设灯照之，果在苍山下。哆怒欲行法，移山于河。山神惧，献宝珠供佛，佑乃已。大中十二年，佑遣段酋迁陷安南都护府。遣段宗榜救缅。榜，汤今云南府宜良县地。人，佑之勇将。先是，狮子国侵缅；屡求救，至是许之。按：缅甸卽汉之掸国，唐之骠国，其历代莫考。当宋元之时，屡败王师。明太祖洪武十年，缅头目招扳南进贡。十九年，使行人司钱古训赍诏立宣尉司。二十年，缅犯景东。二十一年，犯他郞甸，沐英命都指挥宁正平之。三月，犯定边，沐英同都督冯诚平之。景泰三年，王骥赏缅孟养地。缅喜，乃擒献麓川贼。嘉靖初，缅火烧赍金牌官，中终年猖獗海上，遂至难制。○考自永昌府腾越州入缅，止三十四程。腾越一日南甸、一日罗必斯、一日郞、一日甸头、一日甸尾、一日蒙腰、一日甸蓝、一日蒙怜路、一日空地、一日蒙来路、一日大市、一日龙江、一日锅地、一日人列渡、一日江头城、一日景怜、一日及、一日马来城、一日赖当、一日山头、一日甸头、一日阿只、一日吴细辰、一日折弓、一日阿越。由阿越下水，九日卽至缅城。其地有五大城，江头、太公二城之外，又有马来、安正国、蒲甘缅王三城。酋住金楼，民住竹楼。其下称酋为卜剌浪，称酋妻为米泼剌。酋出人乘轿，水有舟筏。官名有招孟、招彔、招刚三等。官无大小，倶金银花宝带。无弓箭。其水有金沙江，险恶，缅恃以为固。涸时，亦仅五里。俗敬佛，重罪对佛发誓，凭僧处断。○入缅又有三道：一由潞江西上；一由腾越七日至麓川；一由景东从木通甸至湾甸渡入芒市，十日至麓川。○此外从潞江上流蒙来渡至景乐沿河有小渡十馀处，皆可通。又有三道：一由天步马，一由湾甸，一由阿郊地界，皆可入缅。宣宗己卯大中十三年，陷播州。李德裕旣贬死，西川节度使所任皆非人，侥佯边功，发兵十万袭滇，自建昌入，佑命子世隆为坦绰，同王嵯巅迎战于古宗，今丽江府铁桥以北地。杀唐兵数万人，立铜柱于界上。世隆之母，佑妃也，出家号师摩矣。尝随佑至罗浮山白城，建一寺，南壁画一龙，是夜龙动，几损寺，妃乃复画一柱锁之，始定。按：妃本渔家女，喜浴。为妃后，仍常泛舟西洱河，屏人潜浴于水，感金龙与交，生世隆。隆七岁，拳握始开，有文在其掌曰：通番打汉。古宗之战，唐帝惧世隆为患，妻以宗室女，伺察其所为。女以世隆年庚潜送于帝。帝使太史推之，知其感龙精而生。是年，丰佑卒于东京，在位三十五年。子世隆立，以王嵯巅摄政。段宗榜救缅，回至腾越，闻佑卒，世隆立，嵯巅摄政，移书王嵯巅曰：「天启不幸，驾崩嗣幼，闻公摄政，国家之福。榜救缅以败狮子国。缅酬金佛，当得敬迎。奈中国无人，惟公望重。榜抵国门之日，烦亲迎佛，与国增光。」云云。嵯巅不知是谋，至日迎之。榜令巅拜佛，突斩之于佛前。讨其弑劝隆晟之罪也。榜熔佛得金数千两。时有缅人奉香火者在榜，默祝曰：「愿世代奉敬，今不如愿，惟愿世尊轮生，灭彼国祚。」后果生郑买嗣篡国，灭蒙氏。
|
|-
|世隆『唐书』作酋龙。　　伪谥景庄皇帝僭称帝始此，以后郑、赵、杨、段、高五姓之国咸效之。
|
|-
|世隆，唐宣宗己卯大中十三年卽位，年十六岁。明年，为懿宗庚辰咸通元年，改元建极。改西京曰中都，东京曰上都。先是，德宗贞元间，西川节度使韦皋开道通南诏，令岁入贡。异牟寻、寻阁劝二世事唐唯谨，迨劝龙晟及丰［佑］，又数数扰边，大为唐患。又以世隆之名犯太宗、元宗庙讳。唐不册封，隆益致怨望。至是自称皇帝，遣兵取乌蛮、僰、爨之地，置东川郡。前节度使杜悰变韦皋制度，侵扰蛮中。隆绝朝贡，寇播州。至是李福为节度使，隆遣清平官董成至成都，移书于福。成与福抗礼，福囚之。上闻，有诏释成，召至京师，见便殿，遣还。咸通二年，遣兵陷安南。左仆射同平章事杜悰言：「西川兵弱，南诏强盛，未可轻绝。宜遣使祭吊，谕令改名，行册礼。帝肯之。会隆复寇嶲州，遂止。咸通三年，隆亲寇蜀，取万寿寺石佛归。时高真寺僧崇模有神术，从征。军中乏粮，又値岁暮，士卒思归，僧咒沙成米，咒水成酒，士卒各醉饱。一日僧化蝶回国乱宫，世隆妻以书达隆。隆答曰：妖若再来，令宫人于其衣背绣蝶。后僧复至，宫人绣之。隆见僧衣有蝶，令斩之。刑七次，首不殊。僧自云：用茅锯之乃断。果然。人见僧魂化一黑鹏飞去，盖僧本高真寺鹏巢中所得之儿也。咸通四年，寇西川。咸通五年，陷安南、邕管。咸通六年，陷嶲州。咸通七年，复攻安南。岭南西道节度使高骈救之，隆兵大败，骈遂定安南。咸通十年，隆遣使杨酋庆等入朝，谢释董成之囚。归成都俘三千人。定边节度使李师望杀其使，隆怒，率众攻蜀，陷嘉州。咸通十一年正月，陷黎州，入卭徕关，围雅州，击卭州，遂进攻成都。次眉州，西川节度使卢耽畏众寡不敌，通使请降。继而唐遣东川节度使颜庆复、大将宋威等率兵来战。世隆败屯星宿山，宋威戍沱江。隆迎战于毗桥，不胜，趋沱江，中伏。城中又出突将，夜火隆营，夺升仙梁。隆大败，奔双流江，无梁以渡，乃伪请和，三日梁成而济。咸通辛卯十二年，立鄯阐王宫。咸通壬辰十三年，于白崖诸葛武侯所立铁柱之地，铸天尊柱，高八尺。蔚昔年曾至铁柱宫，其地界白崖、弥渡、蒙化三境之间。其柱刻字云：建极十三年岁次壬辰四月朔庚子十四日癸丑建立。咸通十四年，攻黔中。又寇西川，作浮梁济大渡河，防河兵马使黄景复伏兵，半渡击败之。会隆国中新兵继至，接战，景复败走。隆进兵陷黎州，入卭徕关。遂遣王保诚等四十人谩书诣剑南节度使牛丛，欲假道入朝，请憩蜀王故殿。丛囚其使三十八人，释酇咙及段酋迁二人还。隆乃退兵至新津而旋。僖宗乙未乾符二年，攻雅州。西川节度使高骈追至大渡河，大败之，俘酋长五十人，收复黎州、卭徕关，斩黄景复以狥。乾符三年，遣使诣高骈请和，不许，斩使者一人。隆怒，自是唐使至不拜，惟拜和尚。骈知之，乃遣僧景仙往谕公主事，隆乃下拜定盟。禧宗丁酉乾符四年二月，复寇蜀，高骈御退之。骈又结吐蓄尚延心嗢、末鲁褥月等为间，筑戎川州、马湖沭沐源川、大渡河三城，列屯拒险，料壮卒为平夷军。世隆气夺，因恚发疽，卒于越嶲景净寺，在位十八年，子隆舜立。
|
|-
|}

===Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆舜，唐僖宗丁酉乾符四年卽位，年十七岁。明年，改元贞明，又改元嵯耶、承知、大同，改国号曰大封民国。遣使于唐请和，诏许之。自劝龙晟至世隆以来，侵蜀伐安南，用兵五十馀年，帑藏不给，横敛于民，上下倶困。舜立，耽于酒色，委政臣下，故愿求和于唐，乃遣段宝诣岭南节度使辛谠，请修好。谠奏，许之，以息边患。乾符六年，遣使于唐求和亲，无表，只用牒，称弟不称臣。唐帝召百官议，礼部侍郞崔澹曰：「南诏无礼，恐贻后笑。」使者上书与澹争。帝谕解之。议者谓中国多故，南诏寖强，不若权与和亲。便从之。僖宗庚子广明元年春正月，唐命宗正少卿李龟年来和亲。僖宗辛丑中和元年，上表款附。中和癸卯三年，唐以宗室女为安化长公主，妻隆舜，僖宗乙已光启元年，遣宰相赵隆眉、清平官杨奇鲲、段义宗三人，朝唐帝行在，且迎公主。高骈在淮阳飞章上言：「三人南诏心腹。宜止而酖之。」唐帝从其言。隆眉等死，南诏遂不复振矣。是年昆仑国进美女，舜嬖之。光启二年地震，龙首、龙尾二关、三阳城皆崩。昭宗己巳乾宁四年，隆舜多内嬖，常信谗以诛其下，淫虐日甚。竖臣杨登弑之于东京，在位二十年，子舜化贞立。
|
|-
|}

===Shunhuazhen舜化贞　　　　　伪谥孝哀帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|舜化贞，唐昭宗丁巳乾宁四年卽位，年二十一岁。明年，改元中兴。上书于唐，朝廷欲报之。利州刺史王建上言：「臣在西南，彼必不敢犯塞，小夷何足辱诏书。」遂止。昭宗光化二年，立五学敎主。十一月，诛杨登，族其家。光化庚申三年，铸崇圣寺丈六观音，清平官郑买嗣合十六国铜所铸，蜀人李嘉亭成像。一说唐天宝间，崇圣寺有僧募造丈六观音像，未就。夜忽雨，旦视之，铜也，卽取以铸像。像成，白光弥覆凡三日夜，至今人称为雨铜观音。唐昭宗壬戌天复二年，舜化贞卒，一说实郑买嗣弑之。，在位五年。化贞有一子，生甫八月，郑买嗣主国事，遂启贞妻曰：「母后深宫，群臣无主，臣当抱太子临朝。」贞妻是其言，以子付之。买嗣抱子出，潜手伤其阴，子哭不已，乃送回宫中。明日，子死。贞妻疑而诘之，买嗣怀不安，遽起兵杀蒙氏亲族八百人于五华楼下，遂簒立焉。
|
|-
|按：蒙氏南诏大蒙国，自细奴逻禅立，起唐太宗己酉贞观二十三年，讫昭宗壬戌天复二年，传十三世，共二百五十五年。
|
|-
|}

==Dachanghe Generations《大长和国　　传三世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dachanghe Generations《大长和国　　传三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|郑买嗣又名。　　　伪谥圣明文武威德桓皇帝。
|
|-
|郑买嗣，又名，唐巂州西泸令陷南诏臣蒙氏，为清平官郑回之七世孙。
隆舜时历官侍中，权势日重。隆舜巡幸无度，留买嗣守国，遂专政柄。舜化贞时为相，化贞卒，嗣贼杀其子，簒蒙国，于唐昭宗壬戌天复二年十二月卽位，年四十二岁，国号大长和，仍都大理。明年，建元安国。后梁太祖开平丁卯元年，建普明寺。开平三年，铸佛一万尊，送寺祈福，为杀蒙氏八百人故也。开平四年八月，买嗣卒，在位八年，子仁旻立。
|
|-
|}

===Renmin 　《仁旻　　　伪谥肃文太上皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|仁旻，后梁太祖庚午开平四年卽位，年二十二岁。明年，改元始元，又改元天瑞、景星、安和、贞佑、初历。末帝甲戌乾化三年，旻攻蜀。蜀高祖王建发兵拒之，旻兵大败，溺水使者万馀人。后唐庄宗癸未开同光元年，施宫寺灾，僧智照撰『封民三宝记』。同光二年旻以朱鬃白马求婚于南汉刘龑，龑以增城公主妻之。明宗丙戌天成元年八月，仁旻饵金丹，躁怒，常杀人，遂暴卒，在位十六年，子隆亶立。
|
|-
|}

===Longdan 　《隆亶　　伪谥恭惠帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆亶，后唐明宗丙戌天成元年卽位，年十二岁，明年，改元天应。明宗戊子天成三年，东川节度使杨乾贞入朝，弑隆亶而立赵善政，计亶在位二年。
|
|-
|按：郑氏大长和国，自买嗣簒位，起唐昭宗癸亥天复三年，讫后唐明宗戊子天成三年，传三世，共二十六年。
|
|-
|大天兴国一作兴源国。　　一世
|
|
|}

==Dayining Generations《大义宁国　　一世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Yang Qianzhen 《杨乾贞　　　伪谥肃恭帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|杨乾贞于后唐明宗己丑天成四年夺大天兴国赵善政之位，改国号曰大义宁国，建元兴圣，又改元大命。乾贞萂村人。今大理府宾川州所属地。母名弥彔，有美色，蒙隆舜私焉。有孕，适渔人杨氏，生乾贞，后又生诏。其父捕鱼，贞立船头，见水中有人龙衣冠冕，左右有凤鸟，白光拥护，乃呼父视之。父见是贞之影，大奇之。长仕郑氏，官至东川节度使。至是夺善政位而自立。贞在位，贪暴特甚，中外咸怨。后晋高祖丁酉天复二年，通海节度使段思平起兵讨之。贞遣弟杨诏等五人出拒。诏兵败，乾贞出奔。思平遂得位，寻赦其罪，废为僧。计贞在位八年。
|
|-
|}


==Dali Generations《大理国　　　传十四世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siping《太祖圣神文武皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|	段思平，其先武威郡北人，世为南诏蒙氏将。唐元宗辛卯天宝十载，及甲午天宝十三载，唐再伐云南，云南王蒙

阁逻凤命世子凤伽异、大军将段俭魏迎战于点苍山及西洱河，两败唐兵。以功升俭魏为清平官，赐名忠国，寻拜相，六传而至思平。其母因过江，水泛触浮木，若有感而娠，生思平，并其弟思良。思平为幕览，小府副将也。常游山中，得为帝之谶，又每多异徵。时东川节度使杨乾贞之弟杨诏者已贵，闻而忌之，使人贼思平。思平逃匿于崇恩寺，在大理府城南九里。捕者追至，见蛛网盈寺门，不入，故得脱。后积战功，使为通海节度使。后唐明宗己丑天成四年，杨乾贞夺赵善政之位。受诏之谮，常欲除思平。平卜于秀山神祠，就其舅爨判自匿。后晋高祖丙申天福元年，乾贞索捕思平甚急。会善政臣守高方，素与思平善，密遣人招思平。思平与其弟思良、军师董迦罗走就之。皆裂冠，变姓名，为猎者，牵一犬至品甸波大村今大理府云南县地。宿旅舍。舍有戟，生牛革裹之，是夜风起，戟忽洞革出。思平惊曰：「是何銛利？得非神戟乎！」问主人曰：「戟何为？」曰：「以防夜耳。」曰：「防夜莫若犬。」遂以犬易戟去。行至叶镜湖，湖在大理府云南县地得神马。饥取野桃而食，核上有虫啮「靑昔」二字，思平解为十二月二十一日，意其吉兆。于是急趋而前，借兵于东方黑爨三十七蛮部，会于石城，今曲靖府是。以董迦罗为军师。兵集之期，适十二月二十一日也。所向皆克，遂进攻大理，讨干贞。时诏等陈兵据桥，军不能过。思平夜忽得三梦：人无首；玉瓶无耳；镜破。觉而告其下。迦罗觧之曰：君乃丈夫，去首为天；玉瓶去耳为王；镜破则无对者，此神示吉兆。是日，有被缨浣沙妇，指渡处曰：「人从我江尾，马从三沙矣，尔国名大理。」从之，乃得过江，击诏等杀之。乾贞闻诏等军败，出奔。思平卽位，时天福丁酉二年也，年四十四岁。建号大理国，建元文德，仍都大理。天福三年封董迦罗为相国，封高方为岳侯，分治成纪、巨桥等地。封爨判为巴甸侯。祠秀山神，免东方三十七蛮部徭役，赦国中凡有罪无子孙者。天福四年，赦杨乾贞罪，废为僧。一说乾贞败后，挈其妻子奔永昌郡。思平遣兵追之，至万剑树，乾贞自缢而死。思平俘其妻子亲属。帝好佛，岁岁建寺，铸佛万尊。后晋出帝甲辰开运元年帝崩，在位八年，子思英立。
|
|-
|}

===Duan Siyin 　《文经皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siyin 　《文经皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思英，后晋出帝甲辰开运元年卽位，明年，为出帝开运二年，改元文经。帝母杨氏桂仙娘没而为神，屡著灵应，封为楡城宣惠圣国母。是年，帝叔思良争位，废帝为僧，法名宏修大师。在位一年，叔思良立。一说思英素不肖，思平在日，常欲废之，不果。迨卽位，愈淫戏无度，群臣废之，而立思良。
|
|-
|}

===Duan Siliang 　《圣慈文武皇帝　　太祖之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siliang 　《圣慈文武皇帝　　太祖之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思良，后晋出帝乙巳开运二年卽位，明年，改元至治。后周太祖壬子广顺二年，帝崩，在位七年，子思聪立。
|
|-
|}

===Duan Sicong 　《思聪　　伪谥至道广慈皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sicong 　《思聪　　伪谥至道广慈皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思聪，后周太祖壬子广顺二年卽位，明年改元明德，又改元广德。宋太祖乙巳开宝二年，思聪卒，在位十七年，子素顺立。
|
|-
|}

===Duan Susun 　《素顺》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Susun 　《素顺》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素顺，宋太祖乙巳开宝二年卽位。明年，改元明政。先是，宋太祖丁卯乾德五年春，王全斌平蜀，还京师，请取云南，负地图进。太祖鉴唐之祸，以玉斧画大渡河为界，曰：「此外非吾有也。」由是段氏得据南诏，相安无事。太宗乙酉雍煕二年，素顺卒，在位十六年，子素英立。
|
|-
|}

===Duan Suyung 　《素英　　　　伪谥昭明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suyung 　《素英　　　　伪谥昭明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素英，宋太祖乙酉雍煕二年卽位。明年，改元广明，又改元明应、明圣、明统、明治。太宗至道二年，述『传灯录』。真宗己酉大中祥符二年，素英卒，在位二十四年，子素廉立。
|
|-
|}

===Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素隆，宋真宗壬戌干兴元年卽位，明年改元明通。仁宗丙寅天圣四年素隆禅位为僧，在位四年。侄素贞真立。
|
|-
|}

===Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素真，宋仁宗丙寅天圣四年卽位，明年改元正治。仁宗辛巳庆历元年素真禅位为僧，在位十五年，孙素兴立。
|
|-
|}

===Duan Suxing 　《素兴　　　　伪谥天明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suxing 　《素兴　　　　伪谥天明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Lianyi　《廉义　　　伪谥上德皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Lianyi　《廉义　　　伪谥上德皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|廉义，宋神宗乙卯熈宁八年卽位。明年，改元上德。遣使入贡于宋。熈宁十年，又改元广安，作八龙王会。神宗庚申元丰三年，杨义贞杀廉义而自立。计义在位五年，自义贞弑其主廉义而自立，簒位仅四月，鄯阐侯高智升命子清平官高升泰起东方爨僰兵，讨而诛之，立廉义之侄寿辉。
|
|-
|}

===Duan Shouhai　《寿辉　　　伪谥上明皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}

===Duan Zhengming　《正明　　思廉之孙　　伪谥保定皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}

==Da Zhongguo Generations　《大中国》==
===Gao Shentai 《高升泰　　伪谥富有圣德表正皇帝》====
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|高升泰，宋哲宗甲戌绍圣元年，受大理国段正明之禅卽位。改国号曰大中国。明年，改元上治。升泰，岳侯高方之裔，大理点苍山莲花峰下芒涌溪人。将生，其父袭岳侯，智升往石云寺在点苍山白雪峰麓进香回，遇一老叟云：「尔家将生贵子，可速归。」智升至家，而升泰适生，心颇异之。及长，有材器，仕为清平官，兼九爽之事，誉望日重。思廉出游，猝遇烈风，吹踣其马。廉将坠，智深跃前扶之。廉德智升，赐以宫人及珠玉。杨允贤（判）〔叛〕，廉命智升讨之，以功加太保，封德侯，旋晋鄯阐侯，世袭。及杨义贞簒逆，智升令升泰起东方兵，诛义贞而立廉义之侄寿辉。辉以智升为布燮，升泰袭鄯阐侯。辉在位灾异迭兴，因禅位于思廉之孙正明。明为君不振，人心归高氏。遂请升泰为君，而正明禅以位焉。哲宗丙子绍圣三年，升泰在位二年，寝疾。遗命曰：「我之立国，以段氏之弱，我死，必以国仍还段氏，愼勿背我。」及卒，其子高泰明遵遗命，还位正明之弟正湻。段氏复兴，号后理国。高氏相之，政令皆出其门，国人称为高国主，段氏拥虚位而已。
|
|-
|}

==Houli Guo Generations 《后理国》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Zhengchen　《段正湻　大理国正明之弟　伪谥中宗文安皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段正湻，宋哲宗丙子绍圣三年复得国，卽位，号后理国。以高泰明为相国，执政柄，高泰运为栅主。明年，改元天授。又改元开明，天政，文安，赦徭役。筑楚雄城，在今楚雄府城西北二里。以封高泰明之侄高明亮。徽宗癸未崇宁二年，遣高泰运奉表入宋，求经籍，得六十九家，药书六十二部。鄯阐李观音得来朝，进金马杖八十节，人民三万三千户。湻赐得八章礼衣，龙头剑，擢为安东将军。蔚按：蒙氏时有安东将军，季李珠所筑安东城，在今大理府赵州城东二里。缅人、波斯、昆仑三国进白象及香物。十月，彗星见西方，大疫。徽宗戊子大观二年，正湻禅位为僧，在位十二年，子和誉立。
|
|-
|和誉又名正严　封云南节度使大理国王，伪谥宪宗宣仁皇帝
|
|-
|和誉，宋徽宗戊子大观二年卽位。明年，改元日新。又改元文治、永嘉、保天、广运。七月中元节，各方贡金银、罗绮、珍宝、犀象万计，牛马遍点苍。徽宗辛卯政和元年，地大震，损十六寺。三十七部判叛〕，高相国泰明讨平之。使四子高明清居鄯阐镇守。政和五年，缅人进金花、犀象。政和六年。遣儒官钟震、黄渐赍敕褒高泰朋相国忠贞，封平国公。是年，遣使入贡于宋。高泰明卒，封国师。泰明生八子，高智昌以罪流死。其下伊、何二人谋为执仇，乘誉入寺进香，图弑逆，事露被收。誉嘉二人之义，赦之，为立义士冢。高泰运立，主国事。六月，三日并出。政和丁酉七年，命子紫琮充进奉使，入贡于宋。诏遣使册封誉为金紫光禄大夫、检校司空、云南节度使、上柱国、大理国王。徽宗己亥宣和元年正月，彗出，慕宁、远、矣、破、马等叛。三月，出师征之，兵败。三十七部蛮复叛。陷鄯阐，高明清死之。郡臣以高升泰侄商量成有德，请立为相，号中国公。徽宗丙午靖康元年五月，金星入月，大火，焚三千九百家。南宋高宗丙辰绍兴六年，王遣使贡象马于宋，广西经畧安抚使奏之，诏护送行在，优礼答之。绍兴十六年三月十四日，大雾，历二十四日方开。高宗丁卯绍兴十七年，王老，因诸子内争外叛、遂禅位为僧，在位三十九年。子正兴立。
|
|-
|}

===Zhengxing 《正兴又名易长　　伪谥景宗正康皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhengxing 《正兴又名易长　　伪谥景宗正康皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|正兴，南宋高宗丁卯绍兴十七年卽位。明年，改元永贞，又改元大宝、龙兴、盛明、建德。高量成让相位与侄寿贞，退老楚雄城。人化其德，名城曰德江城。孝宗癸未隆兴元年三月，寿贞卒。寿昌立为中国公。孝宗壬辰乾道八年四月，重雾，十六日方开。正兴禅位为僧，在位二十五年，子智兴立。
|
|-
|}

===Zhixing 《智兴　　　伪谥宣宗功极皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhixig 《智兴　　　伪谥宣宗功极皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智兴，南宋孝宗壬辰乾道八年卽位，明年，改元利贞。又改元盛德、嘉会、元亨、安定。遣李观音得等至广西横山砦今在广西南宁府江上。求市马。李观音得夺寿昌位，与侄贞明。阿机起兵夺贞明位，还寿昌。贞明遂据鹤庆，号明国公，伪谥义地威天聪明仁帝。高妙音自白崖起兵，据鄯阐。时有妙音之甥成贤、成正二人来谒，意在夺鄯阐。妙音觉之，与之盟于天王庙。二人口含丁香叶，出庙吐之曰：「盟非我也，叶也。」未几，二人起兵，方战，见白马将斩之。白马将，乃庙中二力士也。光宗庚戌绍熙元年，修十六寺。宁宗乙卯庆元元年，修龙首、龙尾二关，三阳城。宁宗庚申庆元六年，智兴卒，在位二十八年，子智廉立。
|
|-
|}

===Zhilian 《智廉　　　伪谥享天皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhilian 《智廉　　　伪谥享天皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智廉，南宋宁宗庚申庆元六年卽位。明年，改元凤历。又改元元寿。使人入宋求『大藏经』一千四百六十五部，置五华楼。宁宗乙丑开禧元年，智廉卒，在位五年。弟智祥立。
|
|-
|}

===Zhixiang 《智祥　　　伪谥神宗皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhixiang 《智祥　　　伪谥神宗皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智祥，南宋宁宗乙丑开禧元年卽位。明年，改元天开。又改元天辅、仁寿。征三十七蛮部，至寻甸平，河水绝流。理宗丁酉嘉（禧）〔熙〕元年，封高隆鄯阐王，以高泰祥为相国，以光日为演习。大府主将也。举贤育才，时和年丰，称治国焉。理宗戊戍嘉（禧）〔熙〕二年，智祥禅位为僧，在位三十三年。子祥兴立。
|
|-
|}

===Xiangxing 《祥兴　　　伪谥孝义皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Xiangxing 《祥兴　　　伪谥孝义皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|祥兴，南宋理宗戊戌嘉（禧）〔熙〕二年卽位。明年，改元道隆。理宗甲辰湻佑四年，蒙古兵出灵关，伐大理。祥兴遣将高禾迎战，禾败死之。段连佑归宋，宋遣使吊祭，致经书、银缎，为高禾拒蒙古兵战殁也。理宗辛亥湻佑十一年，为蒙古宪宗蒙哥之元年，祥兴卒，在位十三年。子兴智立。
|
|-
|}

===Xingzhi 《兴智　　　赠天定贤王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Xiangxing 《祥兴　　　伪谥孝义皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|兴智，南宋理宗辛亥湻佑十一年卽位。明年，改元利正。又改元兴正、天定。是年，南宋理宗壬子湻佑十二年，为蒙古宪宗之二年七月丙午，太弟忽必烈等奉宪宗命，伐大理。受制专征，以大将兀良合台总督军务。八月，次临洮，由六盘逾吐番，凡行山谷二千馀里无人之境。先遣王律术、王侯、王鉴来谕大理，道阻而还。九月，次忒刺，分三道进。兀良合台率西道兵，由晏当路，诸王抄合也只烈率东道兵，由白蛮，忽必烈率劲骑，由中道。乙巳，至满陀城，留其辎重。十月，过大渡河。十一月，至白蛮打郭砦。十二月，再遣三使入大理，招兴智，皆被杀。智命相国高泰祥守金沙江，与蒙古将伯颜不花、虎儿敦等相持。忽必烈命众以革囊潜济江，破吐番，渉摩荻，出石门，所过降之，遂进薄大理。泰祥回军，奉兴智拒战，不胜。蒙古兵入上关。智奔鄯阐，泰祥退至统失逻先为姚安府，府裁，今为姚州，属楚雄府。募兵于三十七部未至，而蒙古兵已长（躯）〔驱〕而入，泰祥被执大理，不屈，乃斩于五华楼下。祥临刑叹日：「段运不回，天使其然，为臣殒首，盖其分也。」时白日正午，忽云起雷震，天鼓大鸣，忽必烈曰：「忠臣也。」泰祥夫人段氏，抱孤儿高琼、高长寿等伸诉。忽必烈目儿顾左右曰：「此忠臣后，宜善视之。」许以世其官。高泰祥为大中国升泰九世孙。遂灭段氏而有其地，得五城、八府、蛮部三十有七。乘胜入吐蕃，降其酋。明年，南宋理宗癸丑宝佑元年，为蒙古宪宗之三年，忽必烈班师。大将兀良合台拔鄯阐，获兴智以献，宪宗命赦之，封为摩诃罗嵯，管领八方，仍守其地，世袭总管。计兴智在位二年，宪宗授兀良合台银印，加大元帅，还镇大理。以刘时中为宣抚使，与兴智同安辑焉。南宋理宗庚申景定元年，为蒙古世祖忽必烈之中统元年，兴智率其季弟段信苴福北行，朝于世祖，道卒。计为总管又七年。蒙古遣使来祭吊，文曰：「段氏承八姓正位，归有新统，旣顺天时以向义，犹得国王以栖迟，实国家待远方之仁，由贤王能左右之义。受命以来，朝夕愓励。赖尔维勤，用征不廷，正当共享亨嘉之运，胡意遽罹霜露之灾，呜呼！当朕未集大统，乃为叔季之国。兹旣承景运，合正君臣之称，参录不替于子孙，诏禄宜昭于典册，特遣太常省祭，赠为后理国向义天定贤王段公，尚赖神麻，永保祚土。所赠王爵，后不为例。」明年，南宋理宗辛酉景定二年。为蒙古世祖中统二年，世祖敕授王之弟信苴日则段实。总管守大理。命之曰：「向率我以临尔境众据国人之请，因从城下之盟，款附而忠勤益著。庸示至优之礼，以彰同视之仁。可革帝号，锡以虎符，总理大理、鄯阐、威楚、统矢、会川、建昌、腾越诸郡，抚恤已附之民，招集未降之国，卿其勉之。」
|
|-
|按：段氏后理国，自段正湻复国，起宋哲宗丙子绍圣三年，讫南宋理宗癸丑（实）［宝应元年，传八世，共一百五十七年。
|
|-
|总计段氏大理、后理二国，传二十二世，共三百零十五年。
|
|-
|增订南诏野史下卷
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>qh88uyopohwzd7gvtdgxy0pvm0z8cim</sha1>
    </revision>
    <revision>
      <id>4669885</id>
      <parentid>4669884</parentid>
      <timestamp>2026-09-13T11:43:14Z</timestamp>
      <contributor>
        <username>Taitesena</username>
        <id>3485636</id>
      </contributor>
      <comment>/* Houli Guo Generations 《后理国》 */</comment>
      <origin>4669885</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="103306" sha1="r2sgtz74s4gskzzngqck6twgz6i29w2" xml:space="preserve">__NOTOC__
{{incomplete translation}}
{{Translation header
 | title    = Unofficial History of Nanzhao (南诏野史)
 | author   = Yang Shen (杨慎)
 | override_editor   = 
 | translator = 'Taitesena'
 | section  =
 | previous =
 | next     =
 | shortcut = 
 | year     = 
 | language = zh
 | original = 
 | notes    =   
}}

== Front Matter ==

# [[Unofficial History of Nanzhao/Translator's Note|Translator's Note]]
# [[Unofficial History of Nanzhao/Influences|Historical Context]]

==Translation==

===Introduction===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Authorship 
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|增订南诏野史上卷 明 四川新都杨愼升庵编辑
|
|-
|}

===The Title of Nanzhao 《南诏之称===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Title of Nanzhao 《南诏之称》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|蛮夷称王曰诏。先时滇有六诏，各据其地。六诏中蒙舍诏最强，后并吞五诏，故独称南诏。
|
|-
|六诏考六诏之地，东西四千里，南北二千九百里
|
|-
|蒙舍诏蒙细奴逻立国，居蒙舍川，地在永昌、姚州之间，处五诏之南。后奴逻曾孙皮逻阁并吞五诏，独称南诏。今蒙化厅是邆赕诏丰咩立国，居邓川。今大理府邓川州是施浪诏施望欠立国。居{{浪穹弥茨河蒙次和山，今大理府浪穹县是浪穹诏丰时立国，居浪穹。后其孙铎罗望迁剑川，改称剑浪诏。今丽江府属剑川州地是越析诏波冲立国。亦称摩诏。又号花马国。居嶲州。今丽江府是后，其兄之子于赠渡泸，邑于龙佉河蒙嶲诏嶲辅立国。居越嶲，今四川宁远府，越嶲厅是
|
|-
|}

===The Territorial Divisions of Nanzhao 《南诏分野》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Territorial Divisions of Nanzhao 《南诏分野》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|在天井鬼入参一度，汉书。次鹑首末位晋书。丽中台上位北斗开阳一星。宋书。在地乃梁州裔土，蜀之苑囿。河图纬。
|
|-
|}

===The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ The Names by which Nanzhao was known throughout History 《南诏历代称名不同 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周鄯阐国、白崖国、昆弥国。战国时滇国，汉西南夷、益州、白子国。后汉建宁国。晋、宋、齐、梁、陈，宁州。隋昆州。唐初，南宁、六诏，唐文宗太和间，名鄯阐府。宋仍名南诏。元名中庆。明名云南省。
|
|-
|	国朝因之。按：汉武帝元狩元年，彩云见南中，在今大理府赵州之白崖。云南之名始此。唐元宗间问蒙舍诏盛逻皮之相张建一作俭成住何处？曰：「南边云下。」因命为云南。又元宗见祥云起，名祥州。今大理府之云南县也。
|
|-
|}

=== General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ General Outline of Successive Nanzhao Rulers' Territorial Control《南诏历代据土总纲》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|鄯阐国蒙苴颂，昆弥国庄蹻、仁果、龙佑那据于周、秦、汉迄六朝。细奴逻据于唐。郑买嗣、赵善政、杨于贞、段思平、高升泰曁正湻，相继据于唐末迄
南宋。凡历有九姓，而雍闓、孟获不与焉。段氏与南宋理宗壬子湻佑十三年为蒙古所灭，而段实于理宗景定二年袭总管，传十二世，明太祖壬戌洪武十五年平云南，擒段世，并段段明之二子苴仁、苴义。赐苴仁官雁门卫镇抚，苴义官武昌卫镇抚，段氏之世土方绝，而又别封其族人段保为大理府云龙州土知州。国朝尚有袭土职者。
|
|-
|}

=== Titles and Official System of Nanzhao《南诏称谓官制》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Titles and Official System of Nanzhao《南诏称谓官制》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|南诏称帝曰骠信，王曰诏，自称曰元，称后曰信么，亦曰九么，妃曰进武，兄曰容，弟曰钟，下曰昶。其设官则有把国事八人，曰坦绰，曰布燮，曰九赞，谓之清平官。曰酋望，曰正酋望，曰员外酋望，曰大（将军）〔军将〕，曰员外。又设九爽之名，爽，省也。功爽主官人，宗爽主户籍，万爽主财用，慈爽主礼，引爽主宾客，幕爽主兵，罚爽主刑，厥爽主工作，禾爽主商贾，皆清平官、酋望、大军将兼之。以清平官子弟为羽仪长八人，清平官见王不得佩剑，惟羽仪长佩之。又有六曹长二人，曹长有功升大军将，凡十二人。又立三托：巨托主仓廪，气托主马，禄托主牛。大府主将曰演习，副曰演览；中府主将曰缮裔，副曰缮览；下府主将曰澹酋，副曰澹览；小府王将日幕撝，副曰幕览。每府有陀酋，陀酋卽掌书记判官之类。外有八节度使：日弄栋节度使，今楚雄府姚州。曰银生节度使，今景东厅及鎭沅州地是。曰永昌节度使，今永昌府是。曰丽水节度使，今丽江府是。曰剑川节度使，今丽江府剑川州是。曰东川节度使，今东川府府是。曰通海节度使，今临安府通海县是。曰拓东节度使。今云南府昆阳州北平定乡，蒙氏子凤伽异曾筑城于此地。又有二都督：曰会川都督，今四川宁远府会理州地是。曰通海都督。又设十睑，蛮语谓州为睑。苴音斜。羊睑，又名羊睑，卽今大理府太和县。赵州睑，今大理府赵州。白崖睑，又名勃弄睑，今赵州之白崖。，云南睑，今大理府云南县。蒙舍睑，今蒙化厅。大厘睑，又名史睑，今太和县喜州。邆川睑，今大理府邓川州。品澹睑，蒙秦睑，矣和睑。三睑未详其地。○蔚按：别本十睑中苴羊睑、赵州睑、白崖睑而下，作义督睑，今剑川州；威远睑，今普洱府威远厅南；河东睑，末详其地；越睑，今永昌府腾越州；北方睑，又名成偈睑，今永北厅；楼头睑，今四川叙永厅，属永宁县；路睑，今楚雄府广通县；与云南睑以下七睑异。○按：又考此七睑中，其越睑、北方睑、楼头睑、路睑凡四睑，见于『汉地里志』及『唐书?南蛮传』中，睑并作赕，音闪，字旣不同，音又各异，似非列于十睑之数。凡人丁壮者皆为战卒。王之亲兵曰朱弩佉苴，音蛆。按：元微之白乐天乐府皆作佉嗟，未审孰是。佉苴，韦带也。每兵百人置罗苴子统一人，戴朱鞮鍪，负犀革铜盾而跣足。自大军将以至曹长，皆系金佉苴尚绛紫，有功加锦，又有功加金波罗。卽虎皮。民兵号白衣，凡民兵出以望苴蛮为先驱。
|
|-
|}

===Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Thirty-Seven Barbarian Clans of Nanzhao《南诏三十七蛮部》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|因远部。威远睑治，其地总名和泥，今元江府是。休腊部。今临安府河西县。嶍峨部。今临安府嶍峨县。屈中部。今临安府阿迷州。溪处甸部、伴溪落恐部。今倶为长官司，属临安府。铁容甸部。今为亏容长官司。官桂思陀部。今为思陀甸长官司，皆属临安府。王弄部、强现三部。今属开化府。师宗部。今广西州师安县。弥勒部。今广西州弥勒县。吉输部、袖恶部。倶在弥勒县地。维摩部。卽广西府维摩州。州裁，今属广西州地。罗雄部。今曲靖府罗平州。纳垢州。今曲靖府马龙州。落温部。今曲靖府陆凉州。磨弥部。今曲靖府沾益州。仁德部。今曲靖府寻甸州。夜苴部卽曲靖府亦佐县，县裁，今归罗平州。强宗部。卽澄江府阳宗县，县裁，今归河阳县。步雄部。今澄江府江川县。罗伽部。卽步雄部分地。休制部。今澄江府新兴州。落蒙州。今澄江府路南州。弥沙部、邑市部。皆落蒙部子孙分治之。阳城堡部。今云南府晋宁州。罗部。今云南府罗次县。乾矢部、罗婺部。倶在武定府曲州，州裁，今属武定州。华竹部。今武定州元谋县。洪农碌券部。今武定州禄劝县。掌鸠法块部在禄劝县城东五里。○以上三十五部在迤东地。白鹿部。今楚雄府。谋统部。今丽江府鹤庆州。○以上二部在迤西地。
|
|-
|}

==Nanzhao through the Generations《南诏历代》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Nanzhao through the Generations《南诏历代》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|白古记：西天天竺摩竭国阿育王骠苴音斜。低娶欠蒙亏为妻，生低蒙苴。苴生九子，长子蒙苴，附罗十六国之祖；次子蒙苴廉，吐蕃之祖；三子蒙苴诺，汉人之祖；四子蒙苴酬，东蛮之祖；五子蒙苴笃，生十二子，七圣五贤，蒙氏之祖；六子蒙苴托，狮子国之祖；七子蒙苴林，交趾国之祖；八子蒙苴颂，白子国仁果之祖；九子蒙苴閦初六切。白夷之祖。○『哀牢今永昌府。夷传』：哀牢蛮蒙伽独捕鱼易罗池在永昌府城南。溺死。其妻沙壹一作壶。往哭之水边，触一浮木，有感而妊，产十子。后携子至池上，木化为龙，人言曰：「我子安在？」九子惊走，独季子背龙而坐，龙舐其背。蛮语谓背为九，坐为隆，故名之曰九隆氏。哀牢山一名天井山，在永昌府。下有妇名奴波息，生十女，九隆弟兄娶之，立为十姓：董、洪、段、施、何、王、张、杨、李、赵，皆刻画其身象龙文，于衣后著尾。子孙繁衍，居九龙山山在永昌府城南。溪谷间，分九十九部，而南诏出焉。
|
|-
|}

===Shanchan Guo《鄯阐国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shanchan Guo《鄯阐国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|周时立国，年代久远，其姓名世次莫考。
|
|-
|}

===Baiya Guo《白崖国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baiya Guo《白崖国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|西天天竺摩竭国阿育王低蒙苴第八子，蒙苴颂居白崖，因地名，号白崖国，传世莫考。后昆弥氏继之，号昆弥国。
|
|-
|昆弥国一名拜国。
|
|-
|昆弥氏，传世姓名莫考。战国时，楚将庄蹻据滇，并有其地，号滇国。
|
|-
|}

===Dian Guo《滇国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dian Guo《滇国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|战国时，楚顷襄王命将庄蹻范蔚宗后汉书作庄豪。将兵循江上，略巴、蜀、黔中以西，蹻至以兵威畧定滇地属楚。欲归报，会秦司马错攻楚，黔中道塞。蹻遂以其众王滇，号滇国，踞之。后有王常羌者好佛，国势不振。法令不行，国人遂推白崖国蒙苴颂之后，白饭王之裔仁果为王，治白崖，于是两国角立。后仁果奉汉，封为白子国。
|
|-
|}

===Baizi Guo《白子国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Baizi Guo《白子国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|汉武帝通西南夷，遣使至滇，求身毒国。滇王常羌问使者曰：「汉孰与我大？」使者还报，武帝怒其言不逊。时白崖国蒙苴颂之后，天竺国白饭王之裔仁果者，为众所推立于白崖。武帝乃册封仁果为王，号白子国。后迁于澄江，今澄江府。迨龙佑那继之，号建宁国。○又一说：白子国之先，有阿育国，王能乘云，上天娶天女，生三子，长季二子封于金马、碧鸡，独封仲子于苍洱之间，崇奉佛敎，不茹晕，日食白饭，人因称为白饭王。迨后有仁果者，汉封为滇王，号白子国。又十五世至龙佑那，后汉诸葛武侯南征，次白崖，以佑那为酋长，赐姓张氏，仍统其民，号建宁国。
|
|-
|}

===Jianning Guo《建宁国》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|后汉后皇帝乙巳建兴三年，益州耆帅雍闓，假鬼术杀建宁太守王昂，归东吴，吴王孙权以闓为永昌守。后汉诸葛武侯南征，至白崖，杀雍闓，擒孟获，乃封白子国王仁果十五世孙龙佑那为酋长，赐姓张氏，于白崖筑建宁城，蔚按建宁城废址在今大理府赵州之弥渡。号建宁国，立铁柱蔚按：今弥渡有铁柱宫，铁柱尚存。先为建宁国王张乐进求甫铸，后南诏蒙世隆复重铸，名曰天尊柱，高八尺。并『南中纪功碑』，铭其背曰：「万岁之后胜我者过此」。迨至隋时，行军总管太平公史万岁征南宁夷爨玩，西破三十馀部，至此，见其碑铭，命左右踣之。其碑跌，中复有志曰：「史万岁不应踣吾碑」。万岁惊异，复树碑，祭拜而去。后张龙佑那仍迁国澄江，传三十二世至十七世孙张乐进求，唐太宗己酉贞观二十三年封为首领大将军。后见蒙舍川蒙细奴罗有奇相，遂妻以女，逊国与之。奴罗自称奇嘉王，建号大蒙国，又称南诏。
|
|-
|}

==Nanzhao《南诏国》==
===13 Generations of Nanzhao 《南诏大蒙国传十三世》 ===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ 13 Generations of Nanzhao 《南诏大蒙国传十三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|细奴一作农。逻一作罗。　伪谥高祖奇嘉王
|
|-
|细奴逻，又名独罗消，西天天竺摩竭国阿育王低蒙苴第五子蒙苴笃之三十六世孙。生有奇相。唐太宗贞观初，其父舍龙尨，又名龙伽独，将奴逻自哀牢避难至蒙舍川，耕于巍山。今蒙化厅之巍宝山。一日，有老僧，美髯，冠赤莲冠，披袈裟，持钵至奴逻家乞食。时奴逻与子逻盛炎方耕巍山之下，其姑与妇将往饁。见僧乞食，遂食之。再炊往饁，僧坐不去。姑妇持饷中道，僧已在彼，复乞食，姑妇又食之。返而复炊，持饁至巍山，则见僧坐盘石上，前有靑牛，左白象，右白马，上覆云气。云中二童子，一执铁杖于左，一执方金镜于右。姑妇惊喜，复以所饷供之。僧问何所愿？姑妇不知对。僧曰：「奕叶相承」。及趣奴逻等至，则但见一人持钵，坐五色云中，而盘石上惟馀衣痕及牛象马之迹耳。奴逻素有祥异，会唐封首领大将军建宁国王张乐进求，以诸葛武侯所立白崖铁柱，岁久剥蚀重铸之。因社会祭柱，柱顶故有金镂鸟，忽能飞，集奴逻左肩，相诫勿动，八日乃去。众骇异，谓天意有属。进求遂妻以女，举国逊之。于唐太宗己酉，贞观二十三年卽位，年三十二岁，建号大蒙国，称奇嘉王，据南诏。高宗庚戌永徽元年，建都蒙舍川，于巃｛山＋于｝山在今蒙化厅西北三十五里。筑巃山＋于城。永徽癸丑四年，遣逻盛炎入朝唐，诏授奴逻为巍州今蒙化厅刺史，赐以锦袍。大勃弄今大理府赵州白崖。酋杨承顚寇麻州，在今曲靖府马龙州城北里许。唐命郞州唐贞观初，分牂牁郡北界置郞州，后改名播州，卽今贵州遵义府。又有郞州，在今云南县地。道行军总管赵孝祖讨之。孝祖先入小勃弄，今云南县地。酋长没盛迎战，孝祖斩之。进至大勃弄，攻其城，破之，擒杨承顚，改云南县为匡州，领勃弄、匡州二县。高宗显庆二年，凤鸣于浪穹罗浮山，乃改名为凤羽山，在大理府浪穹县西南三十里，又名鸟吊山。见『水经注』。封十二圣贤为十二山神。时澄江人波罗旁有经济才，用为文臣；郭郡矣素以勇略闻，用为武臣。又有杨波远者，相传为东汉时人，常骑三角靑牛，号神明大士，能知盐泉，滇中盐泉多为波远所开创。奴逻在位，遵唐正朔。高宗甲戌上元元年，奴逻卒，在位二十六年，子逻盛炎立。
|
|-
|逻盛炎又名逻晟。伪谥世宗兴宗王。
|
|-
|	逻盛炎。唐高宗甲戌上元元年卽位，年四十岁，以张建成为相。明年，盛炎临朝，元宗壬子先天元年，姚州蛮叛归吐蕃。唐命御史李知古讨之，筑城立州县。知古诛豪杰，掠子女，蛮怨，引土蕃，攻杀知古，于姚嶲路绝，而盛炎独奉唐正朔。是年，盛炎卒，在位三十九年，子盛逻皮立。
|
|-
|}


===Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Shengluopi《盛逻皮石刻作诚乐魁　封台登郡王　伪谥太宗威成王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|盛逻皮，唐元宗壬子先天元年卽位，年四十岁。明年为元宗癸丑开元元年，唐授逻皮为特进，封台登郡王今四川宁远府冕宁县地。设官征商税。开元二年，遣张建成入朝于唐。立土主庙。开元九年，皮叛唐。开元十四年，立庙祀晋右将军王羲之为圣人。元宗戊辰开元十六年，逻皮卒，在位十六年，子皮逻阁立。
|
|-
|皮逻一作罗阁石刻作归义王魁乐觉封云南王。
|
|-
|皮逻阁，唐元宗戊辰开元十六年卽位，年三十一岁。开元十八年，灭五诏，自称南诏王。先是，蒙氏恐三十七蛮部不服，选亲族为五诏。未几五诏抗命，逻阁遂赂剑南节度使王昱，求合六诏为一。昱奏于朝，许之。逻阁乃豫建松明大楼，祀祖于上。使人谕五诏曰：「六月二十四日乃星回节蔚按『大理郡志』汉元封间，叶楡妇阿南者为酋长，曼阿娜之妻。娜为汉将郭世忠所杀，欲妻南。南曰：能从三事，当许汝一作幕次祭故夫；一焚故夫衣，易君新衣；一令国人皆知我以礼嫁。忠如其言。明日，聚国人张松幕祭其夫。下置火，南藏刃出，俟火炽焚夫衣，卽引刀刃自断其颈，仆火中，时六月二十五日也。国人哀之，故岁以是日燃炬吊之，名为星回节云。是又当为二十五日。当祭祖，不赴者罪。」四诏听命。惟越析诏波冲之兄子于赠，远不赴会，而邆赕诏丰哶孙｛辵＋皮｝逻邆之妻慈善者，止逻邆勿赴。邆不听。慈善不得已，以铁钏穿于邆臂而行。二十四日，逻邆及施浪诏施望欠弟施望千、浪穹诏丰时孙锋罗望、蒙嶲诏嶲辅子罗原皆至逻阁所。逻阁偕登楼祭祖，祭后享胙食生饮酒，迨晚，四诏尽醉。逻阁独下楼，焚钱遽纵火，火发，兵围之，四诏皆焚死。逻阁遣使至四诏所，报焚钱失火，四诏被焚，状令各诏收骨。四诏妻至，莫辨其骨。独慈善因铁钏得焉，携归葬之。逻阁旣灭四诏，取各诏宫人，念慈善慧而甚美，遣兵围其城，迫取之。慈善曰：「吾岂忘夫事仇者？」闭城坚守，半月城中食尽，慈善度不能支，卽自杀，时七月二十三日也。逻阁嘉其节，乃封赠为宁北妃，并旌其城曰德源城。城废址在今大理府邓川州城东北二里许。开元戊寅二十六年，逻阁破吐蕃及弥蛮，入朝，元宗礼之，加封为特进，云南王，越国公，开府仪同三司，赐名归义，并锦袍金钿带七事。王归国，以兵逐洱河蛮，筑太和城，今大理府城南十五里太和村地是。又筑大厘城今大理府城北四十里喜州是。守之，尽有云南之地。唐授王子阁逻凤右领军卫大将军兼阳瓜州刺史。开元二十七年，明矫叛，破剑川、浪穹、永昌。开元二十八年，王讨朋矫，平之。开元辛已二十九年，王自蒙舍川迁居太和城，立龙首、卽今上关。龙尾卽今下关。二关。唐加阁逻凤为左领军卫大将军。元宗癸未天宝二年，筑羊苴哶城于太和城之北。卽今大理府城。唐迁阁逻凤为左金吾卫大将军，寻拜特进都知兵马大将军。天宝甲申三载，西方进狮子皮。唐加阁逻凤为上柱国。天宝乙酉四载十月，城永昌。天宝丙戌五载，王遣孙凤伽异入唐，唐授伽异为鸿胪少卿，妻以宗室女，赐龟兹乐一部，元宗戊子天宝七载，王卒，在位二十年，子阁逻凤立。
|
|-
|阁罗凤一作觉乐凤。按：『德化碑』云：「家居阁罗凤」，则是取地名以为名也。袭封云南王，伪谥神武王。始建元。
|
|-
|	

阁罗凤，唐元宗天宝戊子七载卽位，年三十六岁。唐遣中使黎敬义持节册凤袭封云南王，敕置阳瓜州于蒙舍川，加授

凤伽异为上卿兼阳瓜州刺史，都知兵马大将军。天宝庚寅九载，王率妻子往谒都督李宓，过云南，太守张虔陀私之，又多徵求。王表虔陀之罪，中官贾奇俊抑之，不得达。王复遣将军杨罗顚等连表控告。元宗仍不省。凤怒，遣大将军王毗双、罗时等发兵攻虔陀。虔陀饮鸩死；遂取姚州，并夷州三十二。获唐嶲州西泸令郑回以归，爱其才，用为清平官。天宝辛卯十载，唐命剑南节度使鲜于仲通将兵八万征云南。凤赴泸南在楚雄府姚州之城北一百五十里。谢罪，愿还所俘掠，请罢兵。仲通不许，分三道而进。仲通自南溪路，大将李晖自会同路，都督王知进自步头路。今临安府地。凤就安宁，再伸衷悃。仲通不听，兵至曲州、靖州。二州今为曲靖府地。凤复遣首领杨子芬、参军江如之赍状，言若不罢兵，卽当归吐蕃，恐云南非唐有。仲通终不许，囚其使，进薄白崖城。别遣大将王天运统师绕出点苍山后。凤遣

凤伽异及大军将段俭魏迎山后师，自逆战于西洱河。唐兵大败，死者六万人，王天运战殁，仲通仅以身免。凤乃叛唐，建元长寿。遣弟阁陂和尚及子铎传、酋望赵佺邓、杨传磨侔等，并子弟六十人献凯吐蕃。陂有神术，人马往来吐蕃，不过朝夕之顷。天宝十一载正月一日，遣宰相倚祥叶乐持金冠、锦袍、金宝带、金帐状、安扛伞鞍、银兽器皿、珂贝、珠毯、衣服、駞马、牛鞻等物至邓川，以凤为兄弟之国，册为赞普钟南国大诏，给金印，称东帝。并授凤伽异大瑟瑟告身，都知兵马大将。凤遂改是年为赞普钟元年。发人口百户于浪穹，筑白崖睑城，又遣兵攻掠安宁。天宝甲午十三载六月，唐命前云南郡都督兼侍御史剑南留后李宓、广府节度使何履光等，率十道兵再征云南。兵逼邓川，凤遣凤伽异、段俭魏迎战于江口。时神川都知兵马使论绮里徐救兵已至巴蹻山，遂诱宓深入，内外夹击。宓粮尽，士卒饥疲，引还。凤以精兵追战，唐全军覆没，李宓被执，沉江死，何履光遁去。凤因进取嶲州会同郡，据清溪关，以破越析。此二役也，皆凤弟阁陂和尚及凤妃白氏行妖术，展帕拍手而笑，韩陀僧用钵法，以故唐兵再败。时唐先后丧师已二十馀万，凤乃敛战胔，筑京观于龙尾关河尾，名万人冢，立碑大书「唐天宝战亡士卒之墓」。而唐宰相杨国忠更揜败以捷闻，叙战功。令清平官郑回撰『德化碑』，唐流寓御史杜光庭书。立石太和国门外，明其不得已叛唐归吐蕃之故。天宝乙未十四载冬十一月，东平郡王安禄山反于范阳，凤乘机以兵取蜀卭州，筑卭子城，及丽水金宝城。升段俭魏为清平官，赐名忠国，旋拜相国。代宗甲辰广德二年，羊苴哶城成，凤名之曰大理城，又名紫城。代宗乙巳永泰元年凤伽异筑云南城卽今云南府省城。又筑拓东城，今云南府昆阳州北平定乡。遂以兵攻陷曲靖。代宗丁已大历十二年，永昌牛生三角，羊生四角，鸡九足，井有光。建观音寺于白崖。先是，逻盛炎时，相国张建成欲于白崖建寺，卜之吉。又地下有三戳观音，上截在西，中截在东，下截在东南。因盛炎旋卒，不果建。至是建寺，掘之果然。代宗戊午大历十三年，阁罗凤卒，在位三十年。因子凤伽异先死，后追谥悼惠王。孙异牟寻立。
|
|-
|异牟寻改国号曰大理国。封云南王，又封南诏王　伪赠廪孝桓王
|
|-
|异牟寻，唐代宗戊午大历十三年卽位，年二十四岁。明年改元见龙，又改上元，率兵三万取蜀为东府，又连土番入寇。唐命神策都将李晟击破之。师还，自称南诏王。德宗甲子兴元元年，牟寻迁居史城，卽大厘城。改号大理国，自称日东王。封岳读，以叶楡今大理府。点苍山为中岳，乌蛮今东川府。乌龙山一名绛云弄山，在今禄劝县东北三百里。为东岳，银生府今景东厅。蒙乐山一名无量山，在厅北九十里。为南岳，又封南安州今楚雄府属。神石亦为南岳，越赕今永昌府腾越州。高黎贡山一名昆仑隅，在腾越、潞江之间。为西岳，嶲州今丽江府是。雪山一名玉龙山，在府西北二十里。为北岳。封金沙江源出吐蓄旄牛徼外犂牛石下，本名犂牛河，又名犂水，讹为丽水。经丽江府、鹤庆州、姚州而东北达于四川马湖府之马湖，卽『山海经』所谓若水。『水经注』云：若水经云南之遂久县，卽今金沙江巡检司地。昔黄帝长子昌意德劣，不足绍承天位，降居斯水为诸侯，娶蜀山氏女，生颛顼于若水之阳，疑卽其地也。祀在武定州，兰沧江源出吐蕃鹿石山下，本名鹿沧，又名兰沧。兰沧讹为浪沧。自丽江府度云龙州至永昌府，东经顺宁府，达于车里，过交趾地而入于南海。祀在丽江府，黑惠江在顺宁府之东入狼沧江，而达于南海。祀在顺宁府，怒江源出西域雍望，奔流而下，深不可测。夏月多瘴，经怒夷地入丽江府境野人界。至永昌府境，乃名潞江。祀在水昌府，为四渎，各建神祠。又立三皇庙。德宗丙寅贞元二年，设官立九爽三托。考疆域，其地东至于铜柱、铁桥、蟠桃、玉楡，东南至于交趾国，南至于骠国，西南至于木落山，西至于太石，西北至于吐蕃，北至于神川，东北至于黔巫。八分之地，属以八演，皆中国降人为之经画者。贞元丁卯三年，寻居大理城。命子弟师事郑回。时寻苦吐蕃徵求无厌，会李泌劝德宗招云南以断吐蕃右臂。帝从之，命韦皋为西川节度使，皋受命招抚群蛮。郑回因说寻归唐，寻以为然。皋遣谍者致书于寻，吐蕃知而疑之，乃责南诏大臣为质。寻愈怨。于是，决计归唐。皋以闻，德宗乃命皋作书谕寻。是年四月，吐番破蜀，来征兵，蔚按：卽吐蕃劫浑瑊清水盟之岁。寻谢绝之。贞元五年，寻遣乌蛮勿邓大鬼主苴梦冲、两林都大鬼主直那时聘于皋，因入朝。皋遣其属崔佐时报之。时吐蕃使数十人先在，佐时至，寻令更衣入。佐时不可，曰：「天朝大使。岂衣夷衣？」寻不得已，夜迎之。佐时至，大宣诏旨，令寻斩番使，去其所立之号。寻遂与佐时盟于点苍山下。贞元九年，寻遣使上表，请从韦皋袭吐蕃。诏册封为云南王，以韦皋为云南安抚使。王遣使诣皋，献夷中歌。贞元十年，吐蕃徵兵于王，王阳示寡弱，以兵三千应之，自将数万人踵其后。正月，袭吐蕃，战于神州，断铁桥，在巨津废州，今丽江府西北地。取十六城，俘其五王，降众十馀万，获军资甲仗无算。遂遣弟凑罗栋、清平官尹仇宽献捷于唐，并献地图、纳贡及吐蕃所给金印，请复号南诏。于是，唐以祠部郞中袁滋为中丞，赐金紫充册使。赐王银窠金印，印文曰：「贞元册南诏印」。王北面跪受。宴使者，出元宗天宝五载所赐王父凤伽异银跳脱马头盘数物，并指老笛工、歌女曰：「皇帝所赐龟兹乐，惟二人在耳！」使者日：「南诏世荷唐恩，当深思祖考子孙勿替，尽忠皇唐。」王对曰：「敢不敬使者之命。」随遣清平官尹辅首入谢，献铎鞘、郁刀、生金、瑟瑟、牛黄、氎、纺丝、越赕绕伦马。蔚按：铎鞘，疑当作择矟，状如残月，有孔旁达，出丽水，饰以金，月祭之血，所击无不洞。段柯古『酉阳杂俎』云：南蛮有毒槊无刀刃，状如朽铁，中人无血立死。言自天而下，入地丈馀，祭地乃掘得之，云云。疑卽铎矟，毒为铎字之讹，槊字本同矟宇也。郁刀铸时以毒药并冶，取莹耀如星者，凡十年乃成，淬以马血，镂金犀饰镡首，伤人卽死。因浪人所铸，又名浪剑，夷中甚宝之。七月，又攻吐蕃，并破施蛮、顺蛮，施蛮、顺蛮卽施浪、浪穹二诏之后，自南诏并吞五诏，五诏之后不复称诏，止称蛮。俘其王置白崖城。贞元十二年，取越赕，置软化城。贞元十四年，请以大臣子弟质于朝，韦皋却之。固请，乃尽舍成都，遣就学。贞元十五年，王开白国北方赕地，今永北厅。徙弥河白蛮及罗落摩蛮实之，号剑羌。是年，王从韦皋再败吐蕃于铁桥。初，王谋击吐蕃，以邆川、卽今邓川州。宁北卽今浪穹县。等城当寇冲，乃峭山深堑，修战备。至是吐蕃谋袭南诏，王告于皋，遣将屯黎州、嶲州以应之。吐蕃引兵攻嶲州，皋严兵以守，别遣将袭击，降其帅，吐蕃惧，退至铁桥。王令人毒其水，吐蕃人马多死，退屯三泸水，王与皋部将杜毗罗击败之。贞元十六年，王率子寻阁劝入朝于唐，召对延英殿，进奉圣乐舞，德宗御麟德殿观之。贞元十七年，王夜绝泸水，斩吐蕃屯卒，又合鬼主破之于泸西。吐蕃大惧，欲悉师收嶲州，以绝南诏。王谓韦皋曰：「吐蕃声取嶲州，实窥云南，请进军羊苴咩城。」皋督诸将分道与王会，陈兵深入，拔木波城。前后凡克城七，焚堡百五十所，斩获无算，生擒论莽热，献于唐，并进铠甲十五万。皋班师，帝遣中使慰抚王。王自是比年贡方物，唐帝深礼之焉。贞元十九年，王封云南金马碧鸡二山之神为景帝，建妙音寺塔，筑大理雪峰长城。宪宗戊子元和三年七月，王卒。唐遣使祭吊，在位三十年，子寻阁劝立。
|
|-
|寻阁一作觉劝又名新觉劝。　袭封南诏王　伪谥孝惠王
|
|-
|寻阁劝，唐宪宗戊子元和三年卽位，年三十一岁。唐册劝袭封南诏王，赐元和金印。宪宗己丑元和四年正月，改元应道，群臣上尊号曰骠信，以鄯阐为东京，大理为西京，重修曲靖崇真寺。寺为晋代所建。十一月王卒，在位一年。子劝龙晟立。
|
|-
|}

===Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quanlongsheng《劝龙晟　　袭封南诏王　　　伪谥幽王 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝龙晟，唐宪宗己丑元和四年卽位，年十二岁。唐册袭封南诏王。明年，改元龙兴。铸佛三尊，送佛顶峰寺，用金三千两。元和九年，晨寇嘉定州，有飞天神兵破之。先是，节度使杜元颖守成都时，时滇兵至嘉定之沐源州，忽自惊溃。蜀军获一夷卒问之，云适见遍山神兵，一神将长斧坐二鬼上，声若迅雷，故尔惊走。至是神复现形，自后追杀，卽时死酋长二人。盖嘉定向有飞天神庙，两破滇兵者，皆此神也。宪宗丙申元和十一年，晟淫虐失道，弄栋节度使王嵯巅弑之，时年仅十九岁，唐命少监李铣祭吊，在位七年，弟劝利立。
|
|-
|}

===Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Quan Li 《劝利 一作劝利晟　　袭封南诏王　　伪谥靖王》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|劝利，唐宪宗丙申元和十一年卽位，年十五岁。唐册袭封南诏王。王嵯巅东寇。明年，改元全义。元和十三年，厚赏王嵯巅，赐姓蒙，封太容。元和十四年，废王嵯巅，赦其罪，命敬信三宝，为清平官。元和十五年，又改元大丰。重修崇圣寺。五月，大雨霖，龙首、龙尾二关倾。除洱河水怪，建龙屋塔。高十二丈。按：『白古记』：唐时洱河有妖蛇，名薄劫，兴大水淹城。蒙国王出示：有能灭之者，赏半官库，子孙世免差徭。部民有段赤城者愿灭蛇，缚刃人水，蛇吞之，人与蛇皆死，水患息。王令人剖蛇腹，取赤城骨葬之，建塔其上，毁蛇骨灰塔，名为灵塔。在今大理府城南龙尾关内点苍山马耳峰下羊皮村。每年有蛇党起风来剥塔灰。时有谣曰：赤城卖硬土。今『龙王庙碑』云：洱河龙王段赤城云。永昌生两头牛。穆宗甲辰长庆四年，赐南诏王金印。是年王卒于东京，在位八年，弟丰佑立。丰佑慕中国之风，独不肯连父名。丰佑石刻作劝丰佑　　册封滇王　　伪谥昭成王
|
|-
|	

丰佑，唐穆宗甲辰长庆四年卽位，年七岁。唐遣京兆少尹韦审规持节册封为滇王。王遣洪成酋等人谢。明年，改元保合，又改元天启。西僧赞陀啒哆建鹤庆元化寺。先是，鹤庆地水淹，僧杖刺东隅泄之。水中得樟木，刻为佛，咒之忽灵，远近名曰活佛。按：活佛，后至明成化间，福建莆田林俊为云南宪副闻之，亲至寺中，将佛火之，得金数百两入官，又毁他寺三百，人呼为林劈佛。建常平仓，筑邓川城。敬宗乙巳宝历元年，重修大理崇圣寺一名三塔寺。成先是，王嵯巅广寺基方七里。圣僧李成眉贤者建立三塔，高三十丈。佛一万一千四百，屋八百九十，铜四万五百九十筋。元和十五年经始，至是工竣。塔顶旧有铁柱款识云：「贞观六年尉迟敬德监造」，盖寺之建久矣。重修云南东寺塔，高百五十尺，西寺塔高八十尺，二寺亦贞观间将作大匠尉迟敬德所建。文宗丁未太和元年，王母出家，法名惠海。太和二年，用银五千，铸佛一堂，废道敎。太和己酉三年，僧梦岛造永昌卧佛，长丈六。六月朔，星落如雨。命王嵯巅等寇蜀。先是，西川节度使杜元颖失士卒心，军逃入南诏，因此知蜀虚实。佑遂遣嵯巅等攻蜀，陷嶲、戎、卭三州，攻成都，止西郛十日，掠经书、宝货、子女无算，蜀中残敝。并寇梓州、蜀州。佑上表于唐，请诛元颖。唐改云南为鄯阐府。卽今云南府省城。太和四年，唐贬杜元颖循州司马，以义成节度使李德裕为西川节度使。裕至西川，建筹边楼，日召习边事者访问，凡山川险要，南道与蛮相入者图之左，西道与吐蕃相接者图之右，不啻身尝经历焉。乃奏请留北兵以重镇守，修甲胄、备器械。率户二百取一人习战，作雄边子弟等十一军。筑仗义、御侮、柔远诸城以扼要害，复卭崃关，徙嶲州治台登，以夺蛮险。令转卭、雅粟以十月而运，先夏而至，人不苦瘴，边境始安。至是使人于佑，责归所俘。太和五年五月，佑归所俘西川四千人于德裕。太和六年，佑掠骠国民三千，徙之拓东城。武宗乙丑会昌元年，佑遣军将晟君筑横渠道自磨用江至于鹤拓，灌东皋及城阳田，与龙佉江合流入于河，谓之锦浪江。又潴点苍山玉局峰顶之南为池，谓之高河，又名冯河。更导山泉共泄流为川，灌田数万顷，民得耕种之利。会昌六年九月，佑攻陷安南，经略使裴元裕死之。宣宗丁卯大宗元年，佑妃卒，佑郁郁不乐，臣下请选妃女备后宫。得罗部今云南府罗次县。一美女进之，有宠。女好佛，建罗次寺，至今灵异。六月大旱，佑令僧寿海祈雨。僧曰：「昔汤旱七年，六事自责，天雨七日。今王酒色妄杀，天怒不雨。王如改悔，天雨自至，何以祈为？」佑如僧言，自责自改，数日果雨。佑女至崇圣寺进香，回至城西，为一乘白马人摄去，寻之不得。佑告于西僧赞陀啒哆，哆曰此山神也。乃设灯照之，果在苍山下。哆怒欲行法，移山于河。山神惧，献宝珠供佛，佑乃已。大中十二年，佑遣段酋迁陷安南都护府。遣段宗榜救缅。榜，汤今云南府宜良县地。人，佑之勇将。先是，狮子国侵缅；屡求救，至是许之。按：缅甸卽汉之掸国，唐之骠国，其历代莫考。当宋元之时，屡败王师。明太祖洪武十年，缅头目招扳南进贡。十九年，使行人司钱古训赍诏立宣尉司。二十年，缅犯景东。二十一年，犯他郞甸，沐英命都指挥宁正平之。三月，犯定边，沐英同都督冯诚平之。景泰三年，王骥赏缅孟养地。缅喜，乃擒献麓川贼。嘉靖初，缅火烧赍金牌官，中终年猖獗海上，遂至难制。○考自永昌府腾越州入缅，止三十四程。腾越一日南甸、一日罗必斯、一日郞、一日甸头、一日甸尾、一日蒙腰、一日甸蓝、一日蒙怜路、一日空地、一日蒙来路、一日大市、一日龙江、一日锅地、一日人列渡、一日江头城、一日景怜、一日及、一日马来城、一日赖当、一日山头、一日甸头、一日阿只、一日吴细辰、一日折弓、一日阿越。由阿越下水，九日卽至缅城。其地有五大城，江头、太公二城之外，又有马来、安正国、蒲甘缅王三城。酋住金楼，民住竹楼。其下称酋为卜剌浪，称酋妻为米泼剌。酋出人乘轿，水有舟筏。官名有招孟、招彔、招刚三等。官无大小，倶金银花宝带。无弓箭。其水有金沙江，险恶，缅恃以为固。涸时，亦仅五里。俗敬佛，重罪对佛发誓，凭僧处断。○入缅又有三道：一由潞江西上；一由腾越七日至麓川；一由景东从木通甸至湾甸渡入芒市，十日至麓川。○此外从潞江上流蒙来渡至景乐沿河有小渡十馀处，皆可通。又有三道：一由天步马，一由湾甸，一由阿郊地界，皆可入缅。宣宗己卯大中十三年，陷播州。李德裕旣贬死，西川节度使所任皆非人，侥佯边功，发兵十万袭滇，自建昌入，佑命子世隆为坦绰，同王嵯巅迎战于古宗，今丽江府铁桥以北地。杀唐兵数万人，立铜柱于界上。世隆之母，佑妃也，出家号师摩矣。尝随佑至罗浮山白城，建一寺，南壁画一龙，是夜龙动，几损寺，妃乃复画一柱锁之，始定。按：妃本渔家女，喜浴。为妃后，仍常泛舟西洱河，屏人潜浴于水，感金龙与交，生世隆。隆七岁，拳握始开，有文在其掌曰：通番打汉。古宗之战，唐帝惧世隆为患，妻以宗室女，伺察其所为。女以世隆年庚潜送于帝。帝使太史推之，知其感龙精而生。是年，丰佑卒于东京，在位三十五年。子世隆立，以王嵯巅摄政。段宗榜救缅，回至腾越，闻佑卒，世隆立，嵯巅摄政，移书王嵯巅曰：「天启不幸，驾崩嗣幼，闻公摄政，国家之福。榜救缅以败狮子国。缅酬金佛，当得敬迎。奈中国无人，惟公望重。榜抵国门之日，烦亲迎佛，与国增光。」云云。嵯巅不知是谋，至日迎之。榜令巅拜佛，突斩之于佛前。讨其弑劝隆晟之罪也。榜熔佛得金数千两。时有缅人奉香火者在榜，默祝曰：「愿世代奉敬，今不如愿，惟愿世尊轮生，灭彼国祚。」后果生郑买嗣篡国，灭蒙氏。
|
|-
|世隆『唐书』作酋龙。　　伪谥景庄皇帝僭称帝始此，以后郑、赵、杨、段、高五姓之国咸效之。
|
|-
|世隆，唐宣宗己卯大中十三年卽位，年十六岁。明年，为懿宗庚辰咸通元年，改元建极。改西京曰中都，东京曰上都。先是，德宗贞元间，西川节度使韦皋开道通南诏，令岁入贡。异牟寻、寻阁劝二世事唐唯谨，迨劝龙晟及丰［佑］，又数数扰边，大为唐患。又以世隆之名犯太宗、元宗庙讳。唐不册封，隆益致怨望。至是自称皇帝，遣兵取乌蛮、僰、爨之地，置东川郡。前节度使杜悰变韦皋制度，侵扰蛮中。隆绝朝贡，寇播州。至是李福为节度使，隆遣清平官董成至成都，移书于福。成与福抗礼，福囚之。上闻，有诏释成，召至京师，见便殿，遣还。咸通二年，遣兵陷安南。左仆射同平章事杜悰言：「西川兵弱，南诏强盛，未可轻绝。宜遣使祭吊，谕令改名，行册礼。帝肯之。会隆复寇嶲州，遂止。咸通三年，隆亲寇蜀，取万寿寺石佛归。时高真寺僧崇模有神术，从征。军中乏粮，又値岁暮，士卒思归，僧咒沙成米，咒水成酒，士卒各醉饱。一日僧化蝶回国乱宫，世隆妻以书达隆。隆答曰：妖若再来，令宫人于其衣背绣蝶。后僧复至，宫人绣之。隆见僧衣有蝶，令斩之。刑七次，首不殊。僧自云：用茅锯之乃断。果然。人见僧魂化一黑鹏飞去，盖僧本高真寺鹏巢中所得之儿也。咸通四年，寇西川。咸通五年，陷安南、邕管。咸通六年，陷嶲州。咸通七年，复攻安南。岭南西道节度使高骈救之，隆兵大败，骈遂定安南。咸通十年，隆遣使杨酋庆等入朝，谢释董成之囚。归成都俘三千人。定边节度使李师望杀其使，隆怒，率众攻蜀，陷嘉州。咸通十一年正月，陷黎州，入卭徕关，围雅州，击卭州，遂进攻成都。次眉州，西川节度使卢耽畏众寡不敌，通使请降。继而唐遣东川节度使颜庆复、大将宋威等率兵来战。世隆败屯星宿山，宋威戍沱江。隆迎战于毗桥，不胜，趋沱江，中伏。城中又出突将，夜火隆营，夺升仙梁。隆大败，奔双流江，无梁以渡，乃伪请和，三日梁成而济。咸通辛卯十二年，立鄯阐王宫。咸通壬辰十三年，于白崖诸葛武侯所立铁柱之地，铸天尊柱，高八尺。蔚昔年曾至铁柱宫，其地界白崖、弥渡、蒙化三境之间。其柱刻字云：建极十三年岁次壬辰四月朔庚子十四日癸丑建立。咸通十四年，攻黔中。又寇西川，作浮梁济大渡河，防河兵马使黄景复伏兵，半渡击败之。会隆国中新兵继至，接战，景复败走。隆进兵陷黎州，入卭徕关。遂遣王保诚等四十人谩书诣剑南节度使牛丛，欲假道入朝，请憩蜀王故殿。丛囚其使三十八人，释酇咙及段酋迁二人还。隆乃退兵至新津而旋。僖宗乙未乾符二年，攻雅州。西川节度使高骈追至大渡河，大败之，俘酋长五十人，收复黎州、卭徕关，斩黄景复以狥。乾符三年，遣使诣高骈请和，不许，斩使者一人。隆怒，自是唐使至不拜，惟拜和尚。骈知之，乃遣僧景仙往谕公主事，隆乃下拜定盟。禧宗丁酉乾符四年二月，复寇蜀，高骈御退之。骈又结吐蓄尚延心嗢、末鲁褥月等为间，筑戎川州、马湖沭沐源川、大渡河三城，列屯拒险，料壮卒为平夷军。世隆气夺，因恚发疽，卒于越嶲景净寺，在位十八年，子隆舜立。
|
|-
|}

===Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Longshun《隆舜一名法　改国号曰大封民国　伪谥宣武帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆舜，唐僖宗丁酉乾符四年卽位，年十七岁。明年，改元贞明，又改元嵯耶、承知、大同，改国号曰大封民国。遣使于唐请和，诏许之。自劝龙晟至世隆以来，侵蜀伐安南，用兵五十馀年，帑藏不给，横敛于民，上下倶困。舜立，耽于酒色，委政臣下，故愿求和于唐，乃遣段宝诣岭南节度使辛谠，请修好。谠奏，许之，以息边患。乾符六年，遣使于唐求和亲，无表，只用牒，称弟不称臣。唐帝召百官议，礼部侍郞崔澹曰：「南诏无礼，恐贻后笑。」使者上书与澹争。帝谕解之。议者谓中国多故，南诏寖强，不若权与和亲。便从之。僖宗庚子广明元年春正月，唐命宗正少卿李龟年来和亲。僖宗辛丑中和元年，上表款附。中和癸卯三年，唐以宗室女为安化长公主，妻隆舜，僖宗乙已光启元年，遣宰相赵隆眉、清平官杨奇鲲、段义宗三人，朝唐帝行在，且迎公主。高骈在淮阳飞章上言：「三人南诏心腹。宜止而酖之。」唐帝从其言。隆眉等死，南诏遂不复振矣。是年昆仑国进美女，舜嬖之。光启二年地震，龙首、龙尾二关、三阳城皆崩。昭宗己巳乾宁四年，隆舜多内嬖，常信谗以诛其下，淫虐日甚。竖臣杨登弑之于东京，在位二十年，子舜化贞立。
|
|-
|}

===Shunhuazhen舜化贞　　　　　伪谥孝哀帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Jianning Guo《建宁国》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|舜化贞，唐昭宗丁巳乾宁四年卽位，年二十一岁。明年，改元中兴。上书于唐，朝廷欲报之。利州刺史王建上言：「臣在西南，彼必不敢犯塞，小夷何足辱诏书。」遂止。昭宗光化二年，立五学敎主。十一月，诛杨登，族其家。光化庚申三年，铸崇圣寺丈六观音，清平官郑买嗣合十六国铜所铸，蜀人李嘉亭成像。一说唐天宝间，崇圣寺有僧募造丈六观音像，未就。夜忽雨，旦视之，铜也，卽取以铸像。像成，白光弥覆凡三日夜，至今人称为雨铜观音。唐昭宗壬戌天复二年，舜化贞卒，一说实郑买嗣弑之。，在位五年。化贞有一子，生甫八月，郑买嗣主国事，遂启贞妻曰：「母后深宫，群臣无主，臣当抱太子临朝。」贞妻是其言，以子付之。买嗣抱子出，潜手伤其阴，子哭不已，乃送回宫中。明日，子死。贞妻疑而诘之，买嗣怀不安，遽起兵杀蒙氏亲族八百人于五华楼下，遂簒立焉。
|
|-
|按：蒙氏南诏大蒙国，自细奴逻禅立，起唐太宗己酉贞观二十三年，讫昭宗壬戌天复二年，传十三世，共二百五十五年。
|
|-
|}

==Dachanghe Generations《大长和国　　传三世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Dachanghe Generations《大长和国　　传三世》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|郑买嗣又名。　　　伪谥圣明文武威德桓皇帝。
|
|-
|郑买嗣，又名，唐巂州西泸令陷南诏臣蒙氏，为清平官郑回之七世孙。
隆舜时历官侍中，权势日重。隆舜巡幸无度，留买嗣守国，遂专政柄。舜化贞时为相，化贞卒，嗣贼杀其子，簒蒙国，于唐昭宗壬戌天复二年十二月卽位，年四十二岁，国号大长和，仍都大理。明年，建元安国。后梁太祖开平丁卯元年，建普明寺。开平三年，铸佛一万尊，送寺祈福，为杀蒙氏八百人故也。开平四年八月，买嗣卒，在位八年，子仁旻立。
|
|-
|}

===Renmin 　《仁旻　　　伪谥肃文太上皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|仁旻，后梁太祖庚午开平四年卽位，年二十二岁。明年，改元始元，又改元天瑞、景星、安和、贞佑、初历。末帝甲戌乾化三年，旻攻蜀。蜀高祖王建发兵拒之，旻兵大败，溺水使者万馀人。后唐庄宗癸未开同光元年，施宫寺灾，僧智照撰『封民三宝记』。同光二年旻以朱鬃白马求婚于南汉刘龑，龑以增城公主妻之。明宗丙戌天成元年八月，仁旻饵金丹，躁怒，常杀人，遂暴卒，在位十六年，子隆亶立。
|
|-
|}

===Longdan 　《隆亶　　伪谥恭惠帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Renmin 　《仁旻　　　伪谥肃文太上皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|隆亶，后唐明宗丙戌天成元年卽位，年十二岁，明年，改元天应。明宗戊子天成三年，东川节度使杨乾贞入朝，弑隆亶而立赵善政，计亶在位二年。
|
|-
|按：郑氏大长和国，自买嗣簒位，起唐昭宗癸亥天复三年，讫后唐明宗戊子天成三年，传三世，共二十六年。
|
|-
|大天兴国一作兴源国。　　一世
|
|
|}

==Dayining Generations《大义宁国　　一世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Yang Qianzhen 《杨乾贞　　　伪谥肃恭帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|杨乾贞于后唐明宗己丑天成四年夺大天兴国赵善政之位，改国号曰大义宁国，建元兴圣，又改元大命。乾贞萂村人。今大理府宾川州所属地。母名弥彔，有美色，蒙隆舜私焉。有孕，适渔人杨氏，生乾贞，后又生诏。其父捕鱼，贞立船头，见水中有人龙衣冠冕，左右有凤鸟，白光拥护，乃呼父视之。父见是贞之影，大奇之。长仕郑氏，官至东川节度使。至是夺善政位而自立。贞在位，贪暴特甚，中外咸怨。后晋高祖丁酉天复二年，通海节度使段思平起兵讨之。贞遣弟杨诏等五人出拒。诏兵败，乾贞出奔。思平遂得位，寻赦其罪，废为僧。计贞在位八年。
|
|-
|}


==Dali Generations《大理国　　　传十四世》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siping《太祖圣神文武皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|	段思平，其先武威郡北人，世为南诏蒙氏将。唐元宗辛卯天宝十载，及甲午天宝十三载，唐再伐云南，云南王蒙

阁逻凤命世子凤伽异、大军将段俭魏迎战于点苍山及西洱河，两败唐兵。以功升俭魏为清平官，赐名忠国，寻拜相，六传而至思平。其母因过江，水泛触浮木，若有感而娠，生思平，并其弟思良。思平为幕览，小府副将也。常游山中，得为帝之谶，又每多异徵。时东川节度使杨乾贞之弟杨诏者已贵，闻而忌之，使人贼思平。思平逃匿于崇恩寺，在大理府城南九里。捕者追至，见蛛网盈寺门，不入，故得脱。后积战功，使为通海节度使。后唐明宗己丑天成四年，杨乾贞夺赵善政之位。受诏之谮，常欲除思平。平卜于秀山神祠，就其舅爨判自匿。后晋高祖丙申天福元年，乾贞索捕思平甚急。会善政臣守高方，素与思平善，密遣人招思平。思平与其弟思良、军师董迦罗走就之。皆裂冠，变姓名，为猎者，牵一犬至品甸波大村今大理府云南县地。宿旅舍。舍有戟，生牛革裹之，是夜风起，戟忽洞革出。思平惊曰：「是何銛利？得非神戟乎！」问主人曰：「戟何为？」曰：「以防夜耳。」曰：「防夜莫若犬。」遂以犬易戟去。行至叶镜湖，湖在大理府云南县地得神马。饥取野桃而食，核上有虫啮「靑昔」二字，思平解为十二月二十一日，意其吉兆。于是急趋而前，借兵于东方黑爨三十七蛮部，会于石城，今曲靖府是。以董迦罗为军师。兵集之期，适十二月二十一日也。所向皆克，遂进攻大理，讨干贞。时诏等陈兵据桥，军不能过。思平夜忽得三梦：人无首；玉瓶无耳；镜破。觉而告其下。迦罗觧之曰：君乃丈夫，去首为天；玉瓶去耳为王；镜破则无对者，此神示吉兆。是日，有被缨浣沙妇，指渡处曰：「人从我江尾，马从三沙矣，尔国名大理。」从之，乃得过江，击诏等杀之。乾贞闻诏等军败，出奔。思平卽位，时天福丁酉二年也，年四十四岁。建号大理国，建元文德，仍都大理。天福三年封董迦罗为相国，封高方为岳侯，分治成纪、巨桥等地。封爨判为巴甸侯。祠秀山神，免东方三十七蛮部徭役，赦国中凡有罪无子孙者。天福四年，赦杨乾贞罪，废为僧。一说乾贞败后，挈其妻子奔永昌郡。思平遣兵追之，至万剑树，乾贞自缢而死。思平俘其妻子亲属。帝好佛，岁岁建寺，铸佛万尊。后晋出帝甲辰开运元年帝崩，在位八年，子思英立。
|
|-
|}

===Duan Siyin 　《文经皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siyin 　《文经皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思英，后晋出帝甲辰开运元年卽位，明年，为出帝开运二年，改元文经。帝母杨氏桂仙娘没而为神，屡著灵应，封为楡城宣惠圣国母。是年，帝叔思良争位，废帝为僧，法名宏修大师。在位一年，叔思良立。一说思英素不肖，思平在日，常欲废之，不果。迨卽位，愈淫戏无度，群臣废之，而立思良。
|
|-
|}

===Duan Siliang 　《圣慈文武皇帝　　太祖之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Siliang 　《圣慈文武皇帝　　太祖之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思良，后晋出帝乙巳开运二年卽位，明年，改元至治。后周太祖壬子广顺二年，帝崩，在位七年，子思聪立。
|
|-
|}

===Duan Sicong 　《思聪　　伪谥至道广慈皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sicong 　《思聪　　伪谥至道广慈皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|思聪，后周太祖壬子广顺二年卽位，明年改元明德，又改元广德。宋太祖乙巳开宝二年，思聪卒，在位十七年，子素顺立。
|
|-
|}

===Duan Susun 　《素顺》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Susun 　《素顺》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素顺，宋太祖乙巳开宝二年卽位。明年，改元明政。先是，宋太祖丁卯乾德五年春，王全斌平蜀，还京师，请取云南，负地图进。太祖鉴唐之祸，以玉斧画大渡河为界，曰：「此外非吾有也。」由是段氏得据南诏，相安无事。太宗乙酉雍煕二年，素顺卒，在位十六年，子素英立。
|
|-
|}

===Duan Suyung 　《素英　　　　伪谥昭明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suyung 　《素英　　　　伪谥昭明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素英，宋太祖乙酉雍煕二年卽位。明年，改元广明，又改元明应、明圣、明统、明治。太宗至道二年，述『传灯录』。真宗己酉大中祥符二年，素英卒，在位二十四年，子素廉立。
|
|-
|}

===Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Sulong 　《素隆　　　　伪谥秉义皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素隆，宋真宗壬戌干兴元年卽位，明年改元明通。仁宗丙寅天圣四年素隆禅位为僧，在位四年。侄素贞真立。
|
|-
|}

===Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suzhen 　《素真　　　　伪谥圣德皇帝  》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素真，宋仁宗丙寅天圣四年卽位，明年改元正治。仁宗辛巳庆历元年素真禅位为僧，在位十五年，孙素兴立。
|
|-
|}

===Duan Suxing 　《素兴　　　　伪谥天明皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Suxing 　《素兴　　　　伪谥天明皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Silian 　《思廉　　太祖元孙　　伪谥兴宗孝德皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|素兴，宋仁宗辛巳庆历元年卽位，明年改元圣明，又改元天明。素兴性好游狎，广营宫室于东京，多植花草，于春登堤上植黄花，名绕道金棱，云津桥上种白花，名萦城银棱。每春月，挟妓载酒，自玉案三泉，溯为九曲流觞。男女列坐，斗草簪花，昼夜行乐。花中有素馨者，以素兴爱之，故名。又有花遇歌则开，有草遇舞则动，兴令歌者傍花，舞者傍草。盖亦花草之妖也。仁宗甲申庆历四年，素兴在位，荒淫日甚，国人废之，而立太祖曾孙智恩之子思廉。计兴在位三年。
|
|-
|}

===Duan Lianyi　《廉义　　　伪谥上德皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Lianyi　《廉义　　　伪谥上德皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|廉义，宋神宗乙卯熈宁八年卽位。明年，改元上德。遣使入贡于宋。熈宁十年，又改元广安，作八龙王会。神宗庚申元丰三年，杨义贞杀廉义而自立。计义在位五年，自义贞弑其主廉义而自立，簒位仅四月，鄯阐侯高智升命子清平官高升泰起东方爨僰兵，讨而诛之，立廉义之侄寿辉。
|
|-
|}

===Duan Shouhai　《寿辉　　　伪谥上明皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}

===Duan Zhengming　《正明　　思廉之孙　　伪谥保定皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|寿辉，宋神宗庚申元豊三年卽位。明年，改元上明，以高智升为布燮，高升泰为鄯阐侯。是年，日月交晦，星辰昼见。寿辉因天变，遂禅位于思廉之孙正明。计辉在位一年。
|
|-
|}

==Da Zhongguo Generations　《大中国》==
===Gao Shentai 《高升泰　　伪谥富有圣德表正皇帝》====
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Shouhai　《寿辉　　　伪谥上明皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|高升泰，宋哲宗甲戌绍圣元年，受大理国段正明之禅卽位。改国号曰大中国。明年，改元上治。升泰，岳侯高方之裔，大理点苍山莲花峰下芒涌溪人。将生，其父袭岳侯，智升往石云寺在点苍山白雪峰麓进香回，遇一老叟云：「尔家将生贵子，可速归。」智升至家，而升泰适生，心颇异之。及长，有材器，仕为清平官，兼九爽之事，誉望日重。思廉出游，猝遇烈风，吹踣其马。廉将坠，智深跃前扶之。廉德智升，赐以宫人及珠玉。杨允贤（判）〔叛〕，廉命智升讨之，以功加太保，封德侯，旋晋鄯阐侯，世袭。及杨义贞簒逆，智升令升泰起东方兵，诛义贞而立廉义之侄寿辉。辉以智升为布燮，升泰袭鄯阐侯。辉在位灾异迭兴，因禅位于思廉之孙正明。明为君不振，人心归高氏。遂请升泰为君，而正明禅以位焉。哲宗丙子绍圣三年，升泰在位二年，寝疾。遗命曰：「我之立国，以段氏之弱，我死，必以国仍还段氏，愼勿背我。」及卒，其子高泰明遵遗命，还位正明之弟正湻。段氏复兴，号后理国。高氏相之，政令皆出其门，国人称为高国主，段氏拥虚位而已。
|
|-
|}

==Houli Guo Generations 《后理国》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Zhengchen　《段正湻　大理国正明之弟　伪谥中宗文安皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段正湻，宋哲宗丙子绍圣三年复得国，卽位，号后理国。以高泰明为相国，执政柄，高泰运为栅主。明年，改元天授。又改元开明，天政，文安，赦徭役。筑楚雄城，在今楚雄府城西北二里。以封高泰明之侄高明亮。徽宗癸未崇宁二年，遣高泰运奉表入宋，求经籍，得六十九家，药书六十二部。鄯阐李观音得来朝，进金马杖八十节，人民三万三千户。湻赐得八章礼衣，龙头剑，擢为安东将军。蔚按：蒙氏时有安东将军，季李珠所筑安东城，在今大理府赵州城东二里。缅人、波斯、昆仑三国进白象及香物。十月，彗星见西方，大疫。徽宗戊子大观二年，正湻禅位为僧，在位十二年，子和誉立。
|
|-
|和誉又名正严　封云南节度使大理国王，伪谥宪宗宣仁皇帝
|
|-
|和誉，宋徽宗戊子大观二年卽位。明年，改元日新。又改元文治、永嘉、保天、广运。七月中元节，各方贡金银、罗绮、珍宝、犀象万计，牛马遍点苍。徽宗辛卯政和元年，地大震，损十六寺。三十七部判叛〕，高相国泰明讨平之。使四子高明清居鄯阐镇守。政和五年，缅人进金花、犀象。政和六年。遣儒官钟震、黄渐赍敕褒高泰朋相国忠贞，封平国公。是年，遣使入贡于宋。高泰明卒，封国师。泰明生八子，高智昌以罪流死。其下伊、何二人谋为执仇，乘誉入寺进香，图弑逆，事露被收。誉嘉二人之义，赦之，为立义士冢。高泰运立，主国事。六月，三日并出。政和丁酉七年，命子紫琮充进奉使，入贡于宋。诏遣使册封誉为金紫光禄大夫、检校司空、云南节度使、上柱国、大理国王。徽宗己亥宣和元年正月，彗出，慕宁、远、矣、破、马等叛。三月，出师征之，兵败。三十七部蛮复叛。陷鄯阐，高明清死之。郡臣以高升泰侄商量成有德，请立为相，号中国公。徽宗丙午靖康元年五月，金星入月，大火，焚三千九百家。南宋高宗丙辰绍兴六年，王遣使贡象马于宋，广西经畧安抚使奏之，诏护送行在，优礼答之。绍兴十六年三月十四日，大雾，历二十四日方开。高宗丁卯绍兴十七年，王老，因诸子内争外叛、遂禅位为僧，在位三十九年。子正兴立。
|
|-
|}

===Zhengxing 《正兴又名易长　　伪谥景宗正康皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhengxing 《正兴又名易长　　伪谥景宗正康皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|正兴，南宋高宗丁卯绍兴十七年卽位。明年，改元永贞，又改元大宝、龙兴、盛明、建德。高量成让相位与侄寿贞，退老楚雄城。人化其德，名城曰德江城。孝宗癸未隆兴元年三月，寿贞卒。寿昌立为中国公。孝宗壬辰乾道八年四月，重雾，十六日方开。正兴禅位为僧，在位二十五年，子智兴立。
|
|-
|}

===Zhixing 《智兴　　　伪谥宣宗功极皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhixig 《智兴　　　伪谥宣宗功极皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智兴，南宋孝宗壬辰乾道八年卽位，明年，改元利贞。又改元盛德、嘉会、元亨、安定。遣李观音得等至广西横山砦今在广西南宁府江上。求市马。李观音得夺寿昌位，与侄贞明。阿机起兵夺贞明位，还寿昌。贞明遂据鹤庆，号明国公，伪谥义地威天聪明仁帝。高妙音自白崖起兵，据鄯阐。时有妙音之甥成贤、成正二人来谒，意在夺鄯阐。妙音觉之，与之盟于天王庙。二人口含丁香叶，出庙吐之曰：「盟非我也，叶也。」未几，二人起兵，方战，见白马将斩之。白马将，乃庙中二力士也。光宗庚戌绍熙元年，修十六寺。宁宗乙卯庆元元年，修龙首、龙尾二关，三阳城。宁宗庚申庆元六年，智兴卒，在位二十八年，子智廉立。
|
|-
|}

===Zhilian 《智廉　　　伪谥享天皇帝 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhilian 《智廉　　　伪谥享天皇帝 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智廉，南宋宁宗庚申庆元六年卽位。明年，改元凤历。又改元元寿。使人入宋求『大藏经』一千四百六十五部，置五华楼。宁宗乙丑开禧元年，智廉卒，在位五年。弟智祥立。
|
|-
|}

===Zhixiang 《智祥　　　伪谥神宗皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Zhixiang 《智祥　　　伪谥神宗皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|智祥，南宋宁宗乙丑开禧元年卽位。明年，改元天开。又改元天辅、仁寿。征三十七蛮部，至寻甸平，河水绝流。理宗丁酉嘉（禧）〔熙〕元年，封高隆鄯阐王，以高泰祥为相国，以光日为演习。大府主将也。举贤育才，时和年丰，称治国焉。理宗戊戍嘉（禧）〔熙〕二年，智祥禅位为僧，在位三十三年。子祥兴立。
|
|-
|}

===Xiangxing 《祥兴　　　伪谥孝义皇帝》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Xiangxing 《祥兴　　　伪谥孝义皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|祥兴，南宋理宗戊戌嘉（禧）〔熙〕二年卽位。明年，改元道隆。理宗甲辰湻佑四年，蒙古兵出灵关，伐大理。祥兴遣将高禾迎战，禾败死之。段连佑归宋，宋遣使吊祭，致经书、银缎，为高禾拒蒙古兵战殁也。理宗辛亥湻佑十一年，为蒙古宪宗蒙哥之元年，祥兴卒，在位十三年。子兴智立。
|
|-
|}

===Xingzhi 《兴智　　　赠天定贤王》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Xiangxing 《祥兴　　　伪谥孝义皇帝》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|兴智，南宋理宗辛亥湻佑十一年卽位。明年，改元利正。又改元兴正、天定。是年，南宋理宗壬子湻佑十二年，为蒙古宪宗之二年七月丙午，太弟忽必烈等奉宪宗命，伐大理。受制专征，以大将兀良合台总督军务。八月，次临洮，由六盘逾吐番，凡行山谷二千馀里无人之境。先遣王律术、王侯、王鉴来谕大理，道阻而还。九月，次忒刺，分三道进。兀良合台率西道兵，由晏当路，诸王抄合也只烈率东道兵，由白蛮，忽必烈率劲骑，由中道。乙巳，至满陀城，留其辎重。十月，过大渡河。十一月，至白蛮打郭砦。十二月，再遣三使入大理，招兴智，皆被杀。智命相国高泰祥守金沙江，与蒙古将伯颜不花、虎儿敦等相持。忽必烈命众以革囊潜济江，破吐番，渉摩荻，出石门，所过降之，遂进薄大理。泰祥回军，奉兴智拒战，不胜。蒙古兵入上关。智奔鄯阐，泰祥退至统失逻先为姚安府，府裁，今为姚州，属楚雄府。募兵于三十七部未至，而蒙古兵已长（躯）〔驱〕而入，泰祥被执大理，不屈，乃斩于五华楼下。祥临刑叹日：「段运不回，天使其然，为臣殒首，盖其分也。」时白日正午，忽云起雷震，天鼓大鸣，忽必烈曰：「忠臣也。」泰祥夫人段氏，抱孤儿高琼、高长寿等伸诉。忽必烈目儿顾左右曰：「此忠臣后，宜善视之。」许以世其官。高泰祥为大中国升泰九世孙。遂灭段氏而有其地，得五城、八府、蛮部三十有七。乘胜入吐蕃，降其酋。明年，南宋理宗癸丑宝佑元年，为蒙古宪宗之三年，忽必烈班师。大将兀良合台拔鄯阐，获兴智以献，宪宗命赦之，封为摩诃罗嵯，管领八方，仍守其地，世袭总管。计兴智在位二年，宪宗授兀良合台银印，加大元帅，还镇大理。以刘时中为宣抚使，与兴智同安辑焉。南宋理宗庚申景定元年，为蒙古世祖忽必烈之中统元年，兴智率其季弟段信苴福北行，朝于世祖，道卒。计为总管又七年。蒙古遣使来祭吊，文曰：「段氏承八姓正位，归有新统，旣顺天时以向义，犹得国王以栖迟，实国家待远方之仁，由贤王能左右之义。受命以来，朝夕愓励。赖尔维勤，用征不廷，正当共享亨嘉之运，胡意遽罹霜露之灾，呜呼！当朕未集大统，乃为叔季之国。兹旣承景运，合正君臣之称，参录不替于子孙，诏禄宜昭于典册，特遣太常省祭，赠为后理国向义天定贤王段公，尚赖神麻，永保祚土。所赠王爵，后不为例。」明年，南宋理宗辛酉景定二年。为蒙古世祖中统二年，世祖敕授王之弟信苴日则段实。总管守大理。命之曰：「向率我以临尔境众据国人之请，因从城下之盟，款附而忠勤益著。庸示至优之礼，以彰同视之仁。可革帝号，锡以虎符，总理大理、鄯阐、威楚、统矢、会川、建昌、腾越诸郡，抚恤已附之民，招集未降之国，卿其勉之。」
|
|-
|按：段氏后理国，自段正湻复国，起宋哲宗丙子绍圣三年，讫南宋理宗癸丑（实）［宝应元年，传八世，共一百五十七年。
|
|-
|总计段氏大理、后理二国，传二十二世，共三百零十五年。
|
|-
|增订南诏野史下卷
|
|-
|}

==Hu Weixianmen Wing DynastyRevisions《大淸湖南武陵胡　蔚羡门订正》==
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Hu Weixianmen Wing Dynasty Revisions《大淸湖南武陵胡　蔚羡门订正》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段氏总管除天定贤王段兴智受封总管七年外起段信苴日卽段实讫段世，共袭十二世。
|
|-
|段实一名信苴日。
|
|-
|段实，于南宋理宗景定二年，蒙古世祖之中统二年，入朝于世祖，袭总管，赐虎符，领大理、威楚、鄯阐、统矢、会川、建昌、腾越等城，自万户以下皆受节制。南宋理宗癸亥景定四年，为元世祖中统四年，蒙古设大理都元帅府，命昔撒昔总制鬼国、大理两路。理宗甲子景定五年，为世祖至元元年，妖僧舍利威结威楚、统矢、鄯阐及三十七蛮部叛，实讨之，大破于威楚、统矢、安宁等处，又破释多罗十馀万众于洱河海口。南宋度宗丁卯咸湻三年，蒙古世祖至元四年，以皇第五子忽哥赤为云南王，镇大理。至元五年，忽哥赤受命与安南国王讨占城、真腊。南宋度宗咸湻六年，世祖至元七年，置大理路军民总管府。南宋度宗辛未咸湻七年，为蒙古世祖至元八年冬十一月，世祖改国号曰元。云南王忽哥赤为元帅寳和丁所杀。元伐金齿、缥甸，降之。分大理三十七蛮部为南北中三路，遣阿鲁忒儿宣抚大理，招谕诸蛮。南宋度宗辛未咸湻十年，元世祖至元十一年，封宗室脱忽鲁为云南王，命云南行省平章政事赛典赤建云南各衙门。妖僧舍利威复叛，实遣石买等诡为商贾，执贽往见，挺矛鏦杀之，枭首于市。元世祖赐实白金及金织纹衣。南宋恭宗丙子德佑二年，元世祖至元十三年，授实为大理等处宣抚使。缅甸叛犯永昌，元命纳速剌丁赛典赤之长子，后封延安王。伐之，破砦三百，因天暑，还师。复命诸王相吾答儿、右丞太卜、参政也罕的斤伐缅，招讨使法烈先驱造舟于阿若、阿禾两江，进拔江头、太公二城，金齿、乌蒙皆降。南宋帝昺庚辰祥兴二年春二月，为元世祖忽必烈之至元十七年，宋亡，元入主中国。以忽哥赤之子也先帖木儿为云南王。命忙兀鲁徵八百媳妇。缅败忽都帖木儿兵，诏思、播土官田、杨二处兵助讨之。命征缅官番听云南王节制。至元辛巳十八年实率子阿庆入觐，元祖嘉其忠，晋大理、威楚、金齿等处宣慰使都元帅。升辞，复拜为云南诸路行中书省参知政事，留阿庆宿卫东宫。至元壬午十九年，实受敕迎征缅师，于金齿病卒。诏以其弟忠为大理宣慰使兼军民万户府，赠实为武定公。实任职二十二年。
|
|-
|}

===Duan Zhong《段忠　实之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Zhong《段忠　实之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段忠，元世祖癸未至元二十年袭。是年，忠随元元帅阔木征芒部、两林蛮及会川等处，破贼立功，元授忠为善阐酋，赐虎符。元置邦牙宣慰司于蒲甘城，命云南王也先帖木儿率招讨使怯烈总兵三千往镇之。忠奉云南王命伐武定。冬十二月忠卒，以实之子阿庆为大理金齿等处宣慰司都元帅、佩金虎符，封宣武将军，晋镇国上将军，尚公主。遣归，复授云南行省参政。忠任职一年。
|
|-
|段庆卽阿庆。实之子
|
|
|-
|段庆，元世祖甲申至元二十一年袭。至元二十五年以云南王也先帖木儿移镇大理，进封营王。至元二十七年冬十月，封皇孙甘剌麻为梁王，镇云南。至元二十九年改封梁王甘剌麻为晋王，镇北边。至元三十年，封甘剌麻之子松山镇云南。至元三十一年世祖崩，孙铁木耳立，是为成宗。成宗丙申元贞二年，置彻里路，卽车里军民宣慰使司。令与八百犬牙相制。秋八百叛命，也先不花征之。成宗己亥大德三年，云南水西土官宋隆济叛，贵州知州张怀德战死。云南行省麻九儿讨之，追杀贼首撒月，斩首五百级。庆奉敕征交趾，平之。入朝，带僧左黎同往，适成宗手疽甚，黎以法水洗之，立愈。帝欲试其术，乃掘地窖，令八人潜其中击鼓，佯云有怪，召黎治之，黎行法，顷之不闻鼓声，启窖视之，则八人已死。帝敬其法，封为国师。大德四年，缅人僧哥伦作乱。缅酋执其兄阿散哥也，寻释去，阿散乃率其党杀酋。酋次子奔诉京师，诏遣薛超兀儿率行省兵讨之。大德五年，金齿、八百叛，不输粮，杀官吏，元命右丞刘深、哈剌带、郑佑等征之。刘深协求水西土妇节金三千两、马三千匹，土官宋隆济遂叛，围深等于穷谷中，梁王阔率兵救，解之。冬，云南地大震，御史陈天祥谏伐西南夷，不报。大德七年，罢徵八百，免右丞刘深官，收符印。左丞相哈剌哈孙议深徼名首衅，丧师辱国，劝帝诛深，遂杀之。深卽往以兵逼南宋帝昺于谢女峡者。大德八年，立平云南碑于点苍山。顺元宣抚宋阿重获其叛叔宋隆济，朝命升职，赐衣一袭。滇池有蛟，化少年淫妇女，有神僧赵伽罗者，命黑胡神擒之，至噀水见形，斩之。神卽土主也。成宗丙午大德十年，罗雄土官阿那龙少叛，据越州。今在曲靖府南六十里，本唐之悦州，其川名鲁望。命右丞汪惟能讨之，追至曲靖，斩那龙少。是年庆卒，弟正袭。庆任职四十三年。
|
|-
|}

===Duan Zheng 《段正　庆之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Zheng 《段正　庆之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段正，元成宗丁未大德十一十年袭。正招蒙化山中生爨入籍。元授正为参政，仍大理军民总管。晋宁建盘龙寺。有神僧觉照者，段氏族人，号莲峰，游东山见龙潭绝幽胜，乃咒龙令徙。龙去，水涸，建寺其地。蔚按：莲峰僧于顺帝之至正末入定塔中。武宗海山戊申至大元年，沾益、乌蒙地大震，三日并出。至大二年三月，梁王松山风疾，诏封皇第七子西平王奥鲁赤之孙老的代镇云南。仁宗爱育黎拔力八达壬子皇庆元年，诏罢徵八百。皇庆癸丑二年冬十月，学士李孟奏准开科，三年一试。时九成殿生芝，天下共取士三百名，每榜云南取五名，内蒙古二名，塞目二名，汉人一名。以八月二十日初场，二十三日次场，二十六日三场。仁宗乙卯延佑二年十一月，封武宗子和世珠为周王，出镇云南。仁宗丙辰延佑三年，正卒，庆子隆袭。正任职十年。
|
|-
|}

===Duan Long 《段隆　庆之子》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Long 《段隆　庆之子》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段隆，元仁宗丁巳延佑四年袭，元授隆为大理军民总管。延佑己未六年，云南行省奏：「夷俗：凡土官无子，卽以妻代管。请听之。」诏曰可。延佑庚申七年，封甘剌麻孙王禅为云南王。英宗硕德八喇癸亥至治三年，进封王禅为梁王，封其子帖木儿不花为云南王。是年八月，诸王按梯不花、索孛罗、月鲁铁木儿等及御史大夫铁失弑帝于南坡行幄。九月泰定帝也孙铁木儿卽位。十二月流诸王月鲁铁木儿于云南。泰定四年，洱海有水怪，牛猪形短项金睛，兴水为患。大理一道人向隆取黄金百镒，隆与之，乃以金为索，沉于河，怪卽日徙于浪穹宁河。按：『六诏灵源记』云：宁河无底。明宣德间，有渔人李应捕鱼，网得金索，旋得旋断。一渔者诫之曰：可止矣。应贪甚，尽曵之，索将穷，惊其怪，风浪陡作，应并舟倶溺，至今为患。文宗图帖睦尔庚午至顺元年，以豫王阿忒思纳失里出镇云南。诸王秃坚据云南叛，杀廉访使，自称云南王。元诏枢密帖木儿讨之，发朵甘思等处兵分道进。至四川建昌、罗罗斯，权寻甸府官曲术集义兵讨秃坚，败贼伯忽于马龙，追至金马山，擒之。是年，隆以老退闲，子俊袭。隆任职十四年。
|
|-
|}

===Duan Jun 《段俊　隆之子》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Jun 《段俊　隆之子》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段俊，元文宗辛未至顺
二年袭，元授俊为云南行省平章。乌撒部奏：「云南驿输征甚苦，愿属四川。」奏下参政贾敦煕议之。是年俊卒，族弟义袭。俊任职一年。
|
|-
|}

===Duan Yi 《段义　俊之族弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Yi 《段义　俊之族弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段义，元文宗壬申至顺三年袭，朝命止授为承务郞、蒙化州知州。是年阿容禾叛于中庆路，义助兵讨平之，以功升参政。九月，乌蒙土官禄馀寇顺元，云南行省遣都事那海奉诏往谕，授馀为参政。冬十一月，云南行省奏：「国马每月上寅日给盐，饮之无病。因伯忽反，盐不给，马多死。」诏四川以盐给之。是年义卒，隆子光袭。义任职一年。
|
|-
|}

===Duan Guang 《段光　隆之子》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Guang 《段光　隆之子》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段光，元顺帝妥权帖睦尔癸酉元统元年袭，朝命止授为承务郞、蒙化州知州。番兵作乱，孟州判官李生等守白崖，値高蓬新败番兵，乗胜长驱破河尾关。光率兵大败之，斩馘无算，河水尽赤，为之不流，得战马甲仗数千。光赋凯旋诗云：「雨锁金门百里城，神州花木管弦声。齐天苍岳参云峻，界地楡河射月明。梵宇三千朝呗朗，招提八百夜香淸。恒沙善果心无异，何患愚夷治不平。」元统二年，光以先与梁王把匝剌瓦尔密孛罗因分域构隙，至是遣张希矫、杨生、张连等发兵攻梁王，不胜，士卒多死，希矫等遁归。顺帝至元元年，梁王侵大理，光自督兵与战于昆弥山卽今大理府赵州南之定西岭，梁王大败。凯还，侍翰杨天甫作『长寿仙曲』上光云：「蒙氏钟王气，驾驭万乗唐。南龙光对北金锁，东洱水朝西点苍，四面固金汤。江绿春杨柳，岸淸古雪霜。屏障龙吟梅破王，竹林鹤立菊舒黄，四季景如妆。此生诚庆幸，有眼睹明王。」光大喜，设宴谢之。顺帝辛巳至正元年，玉案山生水小赤犬，群走如飞。段雄正曰：「此天狗星所化，大兵压境之兆。」经二年方绝。又下铁雨山石，民屋倶穿，人値之多击死。梁王刺杀段氏臣高蓬。先是，光令蓬督兵罗那关，梁王使人暗招之，蓬不从，答之诗云：「寄语下番梁王翁，檄书何苦招高蓬，身为五岳嵩山主，智过六丁缩地公，铁甲铁盔持铁槊，花鞍花索驭花骢，但挥眼前黄石阵，孤云击破几千重。」梁王忌之，乃重贿蓬庖人，刺杀之。顺帝甲申至正四年，光卒，弟功袭。光任职十二年。
|
|-
|}

===Duan Gong 《段功　光之弟》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Gong 《段功　光之弟》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|	段功，元顺帝乙酉至正五年袭，朝命止授为承务郞、蒙化州知州。至正六年，木邦夷思可叛。元命河南参政贾敦熈督师会云南路兵讨之，以功为前锋，屡战克捷。叙功升功为大理总管，寻升参政。至正癸巳十三年，红巾贼流入建昌，旁掠云南边地。阿次失里讨平之。至正十五年三月，元窜太师脱脱于云南。中书右丞哈麻、御史袁赛因不花等陷之也。十二月，左丞相哈麻矫诏杀脱脱于阿轻乞之地，时年四十二岁，天下寃之，两日相荡。是年，梁王宫中有怪。左右启王曰：「盘龙寺僧莲峰，能驱邪。」王礼请至，行法，怪息。王喜，留宫中供养，至夜密问之曰：「今中原纷乱，后事如何？」僧曰：「二十年后祚尽矣。」至期明师果南下。至正十六年，黑井有毒龙，兴水溢井，损民居。莲峰建寺，书铁符沉井中，害息。又宁州有虎咥人，莲峰洒净水驱虎远去，明日虎果去。七月，元以四川廉访使蒲机云为云南诸路廉访使。至正癸卯二十三年三月，红巾贼明玉珍率其党李芝麻同弟明二等将兵三万攻云南。入金马山，梁王把匝剌瓦尔密奔楚雄。四月，梁王发中庆，至石碑村，红巾入城，梁王闻报，感而自咏云：「野无靑草有黄尘，道侧仍多战死人。触目伤心无限事，鸡山还似旧时春。」随命陜西参政车力帖木儿拒之，擒明二。时四方乘机窃发，群盗满山，功乃谋于外外杨智，字渊海者，同稽于卜，卜告吉。又得子宗、子秀兵至，功遂从梁王进兵，吕合败红巾于关滩江。红巾收合馀衂再战，杀段氏之骁将铁万户，又有江心庄人杨胜力战死。梁王为文祭之曰：「生于江心，为我门户，我旧不识，用备其数，能卫社稷，春秋与之，惟忠惟烈，尔则处之，噫! 义重于生，生必有死，丈夫之事，识者有几。愿气作山河，魂归苍洱，英杰复生，以保我之昆裔。」祭毕而哭，一军感泣。是夜，红巾屯古田寺，功令人焚寺，红巾乱，以铁骑捣之，死者大半，追至回蹬关，又大破之。副将谢得攻安宁，功力战杀二千人，谢得奔中庆。于夜功谍者拾得一书，乃明玉珍母寄珍书云：「自尔去后，老母平安，征云南务要得之。兵粮不足，随后发来，不可轻回。」功阅书，令杨智易其辞曰：「自尔去后，老母不安，臣下乱法。又闻中国人马入界，非止一处。尔须急回，迟则难保。大夏天统元年，太后平安书。」遂募亡命者赍书往。有打金箔人陈惠愿行，惟虑老母在。功许养其母，惠遂往。玉珍得书，挥之去令回报，迨夜，玉珍旋军。功追摄至七星关，大破其众。梁王回中庆，奏升功为云南行省平章，以主阿妻之。一日主与宴酣，歌『金指环』云：「将星挺生扶寳阙，寳阙金枝接玉叶。灵辉彻南北东西，皓皓中天光映月。玉文金印大如斗，犹唐贵主结配偶。父王永寿同碧鸡，豪杰长作擎天手。」功久居梁王府，嫡妻高夫人在大理作词寄功云：「风卷残云，九霄冉冉逐。龙池无偶，水云一片绿。寂寞倚帏屏，春雨纷纷促。蜀锦半间，鸳鸯独自宿，珊瑚枕冷，泪滴针穿目，好难禁。将军一去无度，身与影立，影与身独，盼将军只恐乐极生悲寃鬼哭。」至正二十四年春，功还大理，至洱海金鸡庙，夫人遣人适来报生子，功喜，作歌曰：「去时野火通山赤，凯歌回奏梁王怿。自冬抵此又阳春，时物变迁今又昔。归来草色绿无数，桃花正秾柳苞絮。杜鹃啼处日如年，声声只促人归去。」至正二十五年，功思新婚，欲往梁王所。员外杨智于壁间题诗留功，张希矫亦上书留行。功曰：「寳剑岂埋荒土物耶！」矫苦留不已，功怒流矫于顺州。顺州，前明属鹤庆府，今裁在永北厅城西一百二十里。唐时地名牛睒。遂与夫人别，倍道至中庆。梁王疑之，私议曰：「平章此来，得无有吞金马咽碧鸡之心。」其下有姤功者复谗构之。王与阿谋欲以孔雀胆毒功。私泄之，愿与西归。（今）〔令〕功周防，功不信。是年滇大旱，人言定远有禅僧连精，通瑜伽秘密敎，能降龙役鬼。启梁王，王遣人迎至，僧设坛祈雨，咒毕，钵中出一小蛇，遂大雨。王大喜，酬以金帛，辞，役鬼荷担，行空而去。顺帝丙午至正二十六年春，中原盗蠭起，临安廉访使支渭兴三恳休，梁王不允，遣使金闾慰，赐羔羊。渭兴自咏曰：「年高才薄忝淸流，欲挂朝冠不自由。且喜壮怀无诉谍，从敎行道有鸣驺。故园花木无由见，何日干戈定得休。九十春光还欲暮，放怀聊与醉金瓯。」重午节，梁王宫门外观射柳，随侍文武赐宴，支渭兴诗贺曰：「平地如席草如茵，少年将军酒半醺。朱鬣马穿人影过，绿杨枝逐箭锋分。旌旗色映宫前瓦，鼓角声飘海上云。何日鲸鲵倶授首，普天偃武共修文。」七月，梁王偕功东寺讲经，至通济桥，功马逸，王乘机令番将掖杀之。阿闻之恸哭曰：「昨灯下吾犹言，云南施宗施秀二人以胭花殡命，奈何不信。今果然。」命侍女锦被包之，以王礼敛送归大理。诗挽之云：「吾家住在雁门深，一片间云到滇海。心悬明月照靑天，靑天不语今三岁。黄嵩历乱苍山秋，误我一生踏里彩。华言锦被也。吐噜吐噜段阿奴，施宗施秀同奴歹。云片波潾不见人，押不芦花华言起死灵草也。颜色改。肉屏华言骆驼也。独坐细思量，西山铁立华言松林也。风潇洒。」功丧旣行，阿遂不食死，以殉焉。其家臣员外杨智渊海闻而亦死之。智临死诗曰：「半战功名百战身，不堪今日总红尘。死生自古皆由命，祸福于今岂怨人。蝴蝶梦残滇海月，杜鹃啼破点苍春。哀怜永诀云南土，絮酒还敎洒泪频。」明洪武间都督冯诚经功墓，亦歩原韵题诗，吊之曰：「田横五百剑孤身，转眼关山半委尘。北阙玉楼召客记，南滇粉壁说诗人。苍山夜黑云遮月，金马天寒鸟怨春。共惜平章迷绣幕，至今愁听水声频。」功死，长子宝自称平章，立于大理。功任蜀二十二年。
|
|-
|}

===Duan Bao《段宝　功之子 》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Bao《段宝　功之子 》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段宝，于元顺帝丙午至正二十六年八月，因父功为梁王所害，遂自称平章，立于大理。是年，梁王开科取士，以支渭兴主试事。梁王复听谗，诛锄段族。梁段旣结仇，数数构兵。鹤庆知事杨升调和二家，自金鸡庙分界，南属梁王，北属段氏，力劝息兵，百姓稍宁。至正丁未二十七年四月，梁王生日，群臣称贺。王宴于昆明池上，省宪官献诗曰：「贤君添算宴嘉宾，幄殿先施巨海滨。万里晴天开绵绣，一川芳草踏麒麟。笙歌暖送金杯酒，铠仗寛围玉佩人。醉饱百官咸稽首，愿王高寿过千春。」中庆路土主庙圮，梁王重修，立牌纪事。先是，至正十二年庙为耆民杨光所修。至二十三年红巾贼入滇，陷中庆，毁民居，庙亦被焚。梁王欲并段氏，遣人剌宝，弗得。又令平章矢剌七攻大理，皆不克。乃遣使通好，奏授宝为云南右丞，以和之。红巾复入滇，梁王命叔铁木的罕赍敕借兵于宝，宝答书曰：「杀虎母还喂虎子，分狙栗自诈狙，公假途灭虢，献璧吞虞，金印玉书，设钓鱼之香饵，绣阁艳女，备揜雉之网罗。况平章已死，只遗一奴一獒，奴可配阿妃，獒可配华黎氏。二事许诺，当借大兵。不然，金马山换作点苍山，昆明海改作西洱海，兵来矣。」书后又附一诗云：「烽火狼烟信不符，骊山一举任枝梧。平章枉挂红罗帐，员外空题粉壁图。凤去岐山祥兆隐，麟戕大野瑞光无。自从界限鸿沟后，成败兴亡不属吾。」梁王读而深恨之。是年，明太祖取燕京，元顺帝北遁，元亡。明太祖戊申洪武元年，梁王复通好于宝，辞甚卑逊，宝许之和。时有蛮舍兴者，自元江攻入鄯阐，王惧欲出奔，宝以唇齿之故率兵救之，击走舍兴。王德宝，升为武定公。敕曰：「段宝归附而来，忠勤懋著，父子秉忠，征讨克捷，乃于戎马倥偬之中，干戈纷扰之际，不第远朝且兼平乱。宜示至优之数，以彰匡济之勋，兹特升宝为武定公，仍总管大理军民府。尔其不负初心，永保世爵，以光大尔赤城于无穷。宣光元年敕。」云云。宣光乃故元顺帝太子立于应昌年号也。太祖洪武辛亥四年，宝降于太祖，上奏云：「臣闻有天下者为天下之主，有列土者为列土之君。卑臣宝虽隔万里之遥，每切中原之向。大理有二帝三皇之后，一方九姓之传，汉晋六朝以来，大蒙国受封于前唐，残唐五季而终，二理国继守于两宋，臣祖思平等恪共藩复，贡礼屡修于中土，华风远畅于边隅。迨至故元，不尚仁义，专事暴残。顺帝已遁北方，梁王犹祸鄯阐。迩闻明主奉天承运，御极南京，中原太平，边徼宁乂。意者中国有圣人，履尭舜之正统，陋汉唐之浅图，天时人事然也。或命臣依汉唐故例，岁贡天朝，或仿元代职名，俾守旧土。庶深谷回阳，幽扄照日，八方浴德，六合同春，垂怜边境，救恤一方。欲修进贡，恐触明威，合待事体之定，专候圣旨之颁，谨此。」专差段贞、王伯鹘驰奏以闻。太祖诏谕答之。洪武五年，宝女兄名羌娜，小名僧奴，又名宝姑者，适建昌土官阿黎。先是，羌娜绣一旗，至是将嫁，以旗付宝嘱曰：「母常语我云尔父为梁王所害，必当报仇，惟望尔辈长大。我闻母言，故绣此旗已五年矣！今我嫁至夫家，收拾建昌、东川军马，飞报若到，女急来应，愼勿违焉。」临行，又以二诗别宝云：「珊瑚钩起出深闺，满目潸然泪湿衣。氷鉴银台前长大，金枝玉叶下芳菲。鸟飞兔走频来往，桂秀梅香不暂移。惆怅同胞未忍别，应知恨重点苍低。」「何彼秾兮花正红，香车独去洱河东。鸿飞雪岫难经目，风刺霜林易割胸。云白天高连水远，月新春叠与秋重。一作闺里绣旗寃父魄，天边提剑属儿曹。泪珠恰似通宵雨，千里关山几处逢。一作须知恨重苍山小，回首寒云千万重。」洪武辛酉十四年四月，国中巫女歌曰：「莫道君为山海主，山海笑谐谐。园中花谢千万朶，别有明主来。」数日，宝卒，子明袭。宝任职十四年。
|
|-
|}

===Duan Ming《段明　宝之子  》===
{| class=&quot;wikitable&quot; style=&quot;text-align:center; width:80%;&quot;
|+ Duan Ming《段明　宝之子  》
|-
! scope=&quot;col&quot; | Original
! scope=&quot;col&quot; | Translation
|-
|段明，明太祖洪武辛酉十四年四月袭，梁王授明为宣慰使。九月，明太祖命颖川侯溥友德，列侯曹正、王弼、金朝兴，都督郭英、张铨等，率师三十万征云南。帝出饯于龙江。友德至湖广，分遣都督胡海洋、陈桓等领兵五万，由四川永宁趋乌撒。友德等率大军由辰沅趋贵州。进攻普定，擒土酋安瓒，诸苗蛮犵狫闻风迎降。十二月，溥友德等兵至普安，攻下之，进至曲靖。先是，梁王把匝剌瓦尔密遣其司徒平章达里麻将精兵十馀万屯曲靖，以拒明师。沐英曰：「彼谓我师疲于深入，未有虞心，乃可破也。」友德然之，遂倍道进师。将至白石江，忽大雾四塞，冲雾及江而上。顷之雾雾，则两军相望，达里麻见之大惊，以为神军飞至，拥军阵于南岸。沐英分遣一军，沂流潜渡，出其阵后，吹铜角，树旗帜，为疑兵山谷间。达里麻急撤阵后，军以御之，上军阵乱。友德等趣师济江，一涌而渡，旣渡，整列进战。敌众披靡，生擒达里麻，横尸十馀里，俘其众二万人，友德悉慰遣之。友德进击乌撒，分遣沐英等趣云南。梁王闻达里麻破，弃城走晋宁州，忽忽纳岩，寻入滇池岛中，先缢其妃，自饮药不死，投水死之。父老收塟云南城西三十里浄耳山，土人立庙妙音寺侧。后至嘉靖间，拆庙材修社学，乃因旧址为小寺祀之。云南右丞观音保以城降。英等入城，秋毫无犯。收梁王金印并符信图籍，安抚其民。友德亦自曲靖循格孤山而北，以应永宁之兵。时元右丞实卜闻胡海洋等进自永宁，乃聚兵赤水河，以拒之。海洋等造木筏，夜半济河，而友德亦至，实卜遁去。友德令将士于乌撒筑城，版锸方具。蛮众复合，斩首三千馀级，馀众溃散。遂城乌撒，得七星关，以通毕节。又克可渡河，于是东川、乌蒙、芒部诸蛮震惧，望风降附。先是，洪武壬子五年正月，帝遣翰林待制王禕、行参政吴云持诏谕云南梁王，令奉版图来归。梁王初不从，后有降意。至洪武六年十二月，会元太子爱猷识里达刺立于汉北，使侍郞脱脱征饷于云南，脱脱觇知梁王有二心，因以危言逼王，杀使臣以绝其念，王遂杀禕，父老收尸塟地藏寺北。吴云奉使时，会梁王遣铁知院等二十人使沙漠，为边将所获，帝乃释二十人，令与云倶行。至沙塘口，二十人谋曰：「吾等奉使不达，被执而还，罪必死。」乃说云令胡服编发，诈为元使。又逼令改制书，共给梁王。云不从，以死自誓，亦被害。梁王遣人收云骨，塟给孤独寺，及事闻，帝震怒，故有是役。按：王禕字子充，浙江金华府义乌县人。建文时赐谥文节，永乐登极，凡建文设施尽革，遂削禕谥。后至正统中，义乌县丞刘杰奏请，加奉使云南死节臣恤典，禕赐谥文忠。吴云字友云，江苏常州府宜兴县人。至弘治中，赠谥忠节，并祀云南，敕赐为二忠祠。是年冬十二月，明卒，叔世袭。明任职一年。
|
|-
|段世　宝之弟，明之叔
|
|-
|	段（氏）〔世〕，明太祖壬戌洪武十五年袭。二月，世闻鄯阐破，梁王已死，又以沐英等兵略寻甸、临安、澄江、元江、楚雄、洱海，次第皆下，进逼大理，乃遣使致书，请依唐宋故事，奉正朔为外臣。友德不听，答书谕令速降。凡三致书，世怒，遂遣都使张元亨、州判李洪赴军前下战书。畧云：「鄯阐危甚登天，大理险倍投海。英如汉武，昔战仅置益州；雄若胡元，设官止于中庆。取之易而守之难，莫若依吾请乞册封，定为进贡，始为良策。吾实武人，不通经史，前代得失则餍闻也。恭惟麾下振耀皇威，功不亚于孔明，才克比于方叔。涤山川之旧染，历代所未有也。况吾与尔旣无杀父之仇，又无财债之怨，无故交战，真乃不祥。尔屯威楚，彼处之民有何罪焉？若耗人之食，是绝其命；取人之财，是刳其心；摅人妻女，是乱人伦，则吾之应，不得已也。爰念尔等皆中国之人，其中岂无一二达士。得此何益？不得何损？西南之地，号为不毛，易动难安。今春气渐暄，烟瘴渐起，不须杀尔，四五月间，雨霖河泛，尔粮尽气敝，十散九死。形如鬼魅，色如黑漆，欲活不能，汝之进退狼狈矣。莫若乘此，天晴地乾，早寻活路。宁作中原鬼，莫作边地魂，尔宜图之。后理国段明顿首。」书后继一诗云：「长驱虎旅势威宣，深入不毛取暴残。汉武故营旗影灭，唐宗遗垒角声寒。方今天下平犹易，自古云南守独难。拟欲华夷归一统，经纶度量必须寛。」友德、英等览书大怒，拘其使。左副将军蓝玉等率师径进，兵至品甸，世恃田庵和尚有术，列兵五万扼下关。沐英自将攻之，不克。乃命王弼，率兵出洱水之东，趋上关，英以兵缀下关，为犄角势。别遣胡海洋将一军夜度，从石门间绕道出点苍山后，縁崖而上张旗帜。迟明，英先驱，渡河斩关而入，海洋之师亦从山而下，腹背夹攻。世众惊溃，拔其城，世就擒，并执明之二子苴仁、苴义，时二月二十三日也。于是沐英等分兵取鹤庆、丽江，破石门关，荡金齿，所有摩、和泥、车里、品缅等部相率归附。又略建昌，故元平章月普帖木儿降。闰二月，赐云南各土官冠带及诰敕，使任本州岛知州等官。四月，乌撒、东川、芒部诸蛮复叛，溥友德、沐英会兵进讨，斩首三万馀级，诸蛮来降，云南悉平。以乌撒、乌蒙、芒部地近四川，分隶之。九月，土官杨苴等叛，紏众至二十万，攻云南城。都督谢熊、指挥冯诚婴城固守。沐英自乌撒移兵讨之，斩首六万馀级，擒四千馀人，诸部悉定。洪武癸亥十六年二月，故元右丞普颜笃同土酋高大一作天惠叛，据佛光砦。蔚按：佛光砦卽佛光山，山半有洞，可容万人。又名一女关。昔诸葛武侯曾擒孟获于此。在大理府浪穹县东二十里。也先不花叛，据邓川州。溥友德率郭英平之。又定蒙化州，过金沙江，攻北胜府，今永北厅。擒故元平章隔生。于是丽江府、拒津等州皆平，前后斩首一万三千级，蛮民降者四十万户。帝遣耿炳文谕溥友德、蓝玉等班师，沐英留镇云南，别命列侯王志、仇成、张龙分赴寻甸各府，缮城池，立屯堡，安辑人民。是年，械送世并明之二子苴仁、苴义赴京。世临行，以诗别故人杨朝彦云：「雄兵一日破重关，父子流离瞬息间。别后欲知相忆处，锦江流水彩潺潺。」洪武甲子十七年四月，溥友德等班师至京，论平云南功，进封溥友德为颖国公，胡海洋东川侯，陈桓普定侯，张翼鹤庆侯，蓝玉、仇成、王弼、张龙等并赐铁券，子孙世袭。吴复、金朝兴先卒，倶授世袭侯爵，铁券加禄并同。馀升职赐金帛有差。以世、苴仁、苴义见帝，帝诛其头目，谕苴仁、苴义及世曰：「尔祖宝，昔年曾有降表，朕不忍废。」乃授苴仁官雁门卫镇抚，赐名归仁，苴义官武昌卫镇抚，赐名归义。世任职一年，段氏世土，至此而绝。帝又封其族段保为云龙州土知州。
|
|-
|按：段氏袭总管十二世，起南宋理宗辛酉景定二年，为蒙古世祖中统二年，讫明太祖壬戌洪武十五年，共一百二十二年。
|
|-
|}

==References==
{{reflist}}

[[Category:Chinese literature]]
[[Category:Non-fiction books]]
[[Category:Medieval historical works]]
[[Category:Works originally in Chinese]]
[[Category:Pages with foreign language text]]
[[Category:Indigenous peoples]]
[[Category:Guidebooks]]
[[Category:History of China]]
[[Category:Wars]]
[[Category:Diplomacy of China]]
[[Category:Subject:Military history]]

[[zh:蛮书]]</text>
      <sha1>r2sgtz74s4gskzzngqck6twgz6i29w2</sha1>
    </revision>
  </page>
  <page>
    <title>Wikijunior:Farm Alphabet</title>
    <ns>110</ns>
    <id>485578</id>
    <revision>
      <id>4669886</id>
      <timestamp>2026-09-13T11:44:26Z</timestamp>
      <contributor>
        <username>~2026-49455-51</username>
        <id>3625847</id>
      </contributor>
      <comment>Created page with &quot;[[File:Amish farm, Holmes County Ohio.jpg|center|500px]]&lt;br /&gt; &lt;div style=&quot;font-size: xx-large; text-align: center; margin: 0px auto 0px auto;&quot;&gt;'''Wikijunior Farm Alphabet'''&lt;/div&gt;   &lt;noinclude&gt; &lt;div style=&quot;font-size: large; text-align: center; margin: 0px auto 0px auto;&quot;&gt;-- [[/A/]]  [[/B/]]  [[/C/]]  [[/D/]]  [[/E/]]  [[/F/]]  [[/G/]]  [[/H/]]  [[/I/]]  [[/J/]]  [[/K/]]  [[/L/]]  [[/M/]]  [[/N/]]  [[/O/]]  [[/P/]]  [[/Q/]]  [[/R/]]  [[/S/]]  [[/T/]]  [[/U/]]  [[/V/]]  [...&quot;</comment>
      <origin>4669886</origin>
      <model>wikitext</model>
      <format>text/x-wiki</format>
      <text bytes="627" sha1="m27myvomzqkzlgb56mawqubti6ybjfi" xml:space="preserve">[[File:Amish farm, Holmes County Ohio.jpg|center|500px]]&lt;br /&gt;
&lt;div style=&quot;font-size: xx-large; text-align: center; margin: 0px auto 0px auto;&quot;&gt;'''Wikijunior Farm Alphabet'''&lt;/div&gt;


&lt;noinclude&gt;
&lt;div style=&quot;font-size: large; text-align: center; margin: 0px auto 0px auto;&quot;&gt;-- [[/A/]]  [[/B/]]  [[/C/]]  [[/D/]]  [[/E/]]  [[/F/]]  [[/G/]]  [[/H/]]  [[/I/]]  [[/J/]]  [[/K/]]  [[/L/]]  [[/M/]]  [[/N/]]  [[/O/]]  [[/P/]]  [[/Q/]]  [[/R/]]  [[/S/]]  [[/T/]]  [[/U/]]  [[/V/]]  [[/W/]]  [[/X/]]  [[/Y/]]  [[/Z/]] --
&lt;/div&gt;
&lt;/noinclude&gt;
{{Shelves|Wikijunior pre-reader books}}{{Status|100%}}
&lt;noinclude&gt;
{{reading level|Pre-reader}}</text>
      <sha1>m27myvomzqkzlgb56mawqubti6ybjfi</sha1>
    </revision>
  </page>
</mediawiki>