Embedded Xinu Documentation Release master Douglas Comer, Dennis Brylow, and others March 03, 2015 Contents 1 Introduction 1 1.1 Getting started..............................................1 1.2 Teaching with Embedded Xinu.....................................1 1.3 Supported platforms...........................................2 1.4 The original Xinu............................................2 2 Getting started with Embedded Xinu3 2.1 Downloading the source code......................................3 2.2 Choosing a platform...........................................4 2.3 Setting up a cross-compiler.......................................4 2.4 Compiling Embedded Xinu.......................................6 2.5 Next steps................................................7 2.6 Other resources..............................................8 3 Components and Features (platform independent)9 3.1 Preemptive multitasking.........................................9 3.2 Shell................................................... 10 3.3 TTY driver................................................ 14 3.4 Memory management.......................................... 15 3.5 Message passing............................................. 17 3.6 Mailboxes................................................ 17 3.7 Standard C Library............................................ 18 3.8 Networking................................................ 19 3.9 USB................................................... 31 3.10 USB keyboard driver........................................... 36 4 MIPS ports (including Linksys routers) 39 4.1 Common Firmware Environment.................................... 39 4.2 EJTAG.................................................. 42 4.3 EJTAG ID Codes and Implementation Registers............................ 43 4.4 Exception and Interrupt Handling (MIPS)................................ 47 4.5 Flash driver................................................ 47 4.6 Flash memory.............................................. 48 4.7 General purpose input and output.................................... 50 4.8 Backing up your router.......................................... 51 4.9 Connecting to a modified router..................................... 53 4.10 Installing OpenWRT........................................... 57 4.11 Modifying the ASUS hardware..................................... 58 i 4.12 Modifying the Linksys hardware..................................... 62 4.13 Recovering a router........................................... 69 4.14 Memory................................................. 75 4.15 Mips console............................................... 78 4.16 mipsel-qemu............................................... 79 4.17 Processor................................................. 79 4.18 Serial adapter diagrams......................................... 81 4.19 Startup.................................................. 87 4.20 Switch driver............................................... 87 4.21 TRX header............................................... 88 4.22 UART driver............................................... 89 4.23 WRT54GL................................................ 91 5 ARM ports (including Raspberry Pi) 93 5.1 Interrupt Handling (ARM)........................................ 93 5.2 Preemptive multitasking (ARM)..................................... 95 5.3 arm-qemu................................................. 96 5.4 Raspberry Pi port............................................. 97 6 Teaching with Embedded Xinu 107 6.1 Monitors................................................. 107 6.2 Compiler Construction With Embedded Xinu.............................. 107 6.3 Building a Backend Pool......................................... 109 6.4 Deploying Xinu............................................. 116 6.5 Building an Embedded Xinu laboratory................................. 120 6.6 Networking with Xinu.......................................... 121 6.7 Student Built Xinu............................................ 123 6.8 Student Extended Xinu.......................................... 126 6.9 Xinu Helper Class............................................ 127 6.10 Assignments............................................... 128 6.11 Operating Systems Tracks........................................ 162 6.12 Networking................................................ 162 6.13 Compilers................................................ 163 6.14 Building a Backend Pool......................................... 163 6.15 Workshops................................................ 163 6.16 Acknowledgements........................................... 163 7 Projects 165 7.1 Curses.................................................. 165 7.2 WinX................................................... 166 7.3 WinXinu................................................. 169 7.4 WinXinu Installation........................................... 170 7.5 XinuPhone................................................ 172 7.6 Xipx................................................... 175 8 Development 177 8.1 Git repository............................................... 177 8.2 Kernel Normal Form (KNF)....................................... 177 8.3 Trace................................................... 182 8.4 Build System............................................... 182 8.5 Porting Embedded Xinu......................................... 183 8.6 Documentation.............................................. 185 8.7 Systems Laboratory........................................... 187 ii CHAPTER 1 Introduction Note: This documentation, generated from files distributed with the Embedded Xinu source code, is currently under development as a replacement for the Embedded Xinu Wiki (http://xinu.mscs.mu.edu). Embedded Xinu is an ongoing research and implementation project in the area of Operating Systems and Embedded Systems. Its original goal was to re-implement and port the Xinu Operating System to several embedded MIPS plat- forms, such as the Linksys WRT54GL router. Since then, Embedded Xinu has been ported to other platforms, such as the QEMU MIPSel virtual environment and the Raspberry Pi; see the list of supported platforms. Although Embedded Xinu is still being developed and ported to new platforms, a laboratory environment and curriculum materials are already in use for courses in Operating Systems, Hardware Systems, Embedded Systems, Networking, and Compilers at Marquette University and other colleges/universities. The Embedded Xinu project was conceived and is supervised by Dr. Dennis Brylow and is being conducted by both graduate and undergraduate students in the Systems Laboratory in the Math, Statistics, & Computer Science department of Marquette University in Milwaukee, Wisconsin. The first major phase of work on Embedded Xinu began in the Summer of 2006. Our project partners include Dr. Bina Ramamurthy at University of Buffalo (with whom we shared an NSF CCLI grant), Dr. Paul Ruth at University of Mississippi, and Dr. Doug Comer (father of Xinu) at Purdue University. 1.1 Getting started To get started by downloading, compiling, and running Embedded Xinu, see Getting started with Embedded Xinu. For information about the features of Embedded Xinu, see Components and Features (platform independent). Information about specific platforms is also available: • ARM ports (including Raspberry Pi) • MIPS ports (including Linksys routers) 1.2 Teaching with Embedded Xinu For curriculum guidance on adopting or adapting Embedded Xinu for undergraduate coursework, see Teaching with Embedded Xinu. For information about building an Embedded Xinu laboratory environment, see Building an Embedded Xinu labora- tory. 1 Embedded Xinu Documentation, Release master 1.3 Supported platforms These are all the platforms on which Embedded Xinu currently runs. Plat- Status Comments PLAT- Cross- form FORM target value Linksys Supported This is our primary development platform, on which Xinu has wrt54gl mipsel WRT54GL been tested thoroughly. Linksys Supported Tested and running at the Embedded Xinu Lab. Supported via wrt54gl mipsel WRT54G same code as WRT54GL. v8 Linksys Probably The v4 is apparently the version on which WRT54GL is based, wrt54gl mipsel WRT54G Supported and so although the Embedded Xinu Lab has not explicitly v4 tested it, it probably works. Linksys Supported Newer model of WRT54GL. Full O/S teaching core functioning, wrt160nlmips WRT160NL including wired network interface. Linksys Supported Full O/S teaching core functioning, including wired network e2100l mips E2100L interface. ASUS Not This platform was working in the past but is no longer being wl330ge mipsel WL- actively actively maintained or tested. 330gE main- tained mipsel- Supported Full O/S teaching core functioning, network support in progress. mipsel-qemumipsel qemu Rasp- Supported Core operating system including wired networking is functional. arm-rpi arm-none-eabi berry Pi arm- Supported Core operating system, excluding wired networking, is arm-qemuarm-none-eabi qemu functional. 1.4 The original Xinu The original Xinu (“Xinu is not unix”) is a small, academic operating system to teach the concepts of operating systems to students. Developed at Purdue University by Dr. Douglas E. Comer in the early 1980s for the LSI-11 platform, it has now been ported to a variety of platforms. Embedded Xinu is an update of this project which attempts to modernize the code base and port the system to modern RISC architectures such as MIPS, while keeping