SYLLABLE FREQUENTLY ASKED QUESTIONS: Last-modified: 01 May 2006 Version: syllable_faq.txt(2) 1. General 1.1 What is Syllable? 1.2 Where did Syllable come from? 1.3 What happened to Kurt/Atheos? 1.4 Is it possible to use Syllable in a text-only mode? 1.5 How do I properly shutdown or reboot Syllable? 1.6 I have a serial mouse; why doesn't it worK? 1.7 The GUI looks like an Amiga. Is Syllable an AmigaOS clone? 1.8 How do I take a screenshot? 1.9 How do I get non-English characters (e.g. ? or ?) to work in the keymap I've set up? 1.10 What do I need to modify in order to support Chinese (Big-5) text? 1.11 How much disk space do I need to install Syllable? 1.12 How often are new releases of Syllable? 1.13 Where can I find more information about Syllable? 1.14 Where can I find software for Syllable? 1.15 The API looks like BeOS. Is Syllable a BeOS clone? 1.16 Does Syllable run under Bochs/VMWare/Virtual PC/...? 1.17 What licence is Syllable available under? 1.18 How far advanced is Syllable's development? 1.19 What are Syllable's system requirements? 1.20 What architectures does Syllable run on? 1.21 How can I become involved in development? Are newcomers allowed to join the effort? 2. Emulation. 2.1 Does Syllable run under VMWare? 2.2 Where can I get a VMware image with Syllable already installed? 2.3 Why is my screen messed up in Syllable? 2.4 Does Syllable support the AMD PCNET network card in VMware? 2.5 Why won't Syllable boot in VMware? 2.6 Why won't the Syllable ISO images boot in VMware? 2.7 Does Syllable run under Bochs? 2.8 Does Syllable run under Virtual PC? 2.9 What Virtual PC hardware is supported? 2.10 What versions of Virtual PC will work? 2.11 How do I install Syllable under Virtual PC? 2.12 Do you know where I can get a Virtual PC disk image of Syllable? 3. Development 3.1 I have installed the GCC package but whenever I try to compile anything I get the "cannot find binutils" error. 3.2 Can I contribute to the development of Syllable? 3.3 What documentation is available on porting a Linux driver to Syllable? 3.4 How do I build Syllable from scratch with GCC on a Linux machine? 3.5 I get segfauits when calling libatheos methods, like Desktop().GetResolution(). Why? 3.6 What are the best source-code examples to study for using bitmaps? 3.7 How can I make a Bitmap from a raw pixel data? 3.8 How do you copy raw data into the Bitmap class? 3.9 How do I make a keymap? 3.10 OK, I've made a keymap. How do I get it into the distribution? 3.11 What are the differences between the Linux and Syllable driver interfaces? 3.12 Can I test a driver implementation from userspace, or are the syscalls the driver uses only reachable from kernelspace? 3.13 Why not port Syllable to another kernel? 3.14 Why not use X-Windows and X's GUI toolkits? 4. Technical 4.1 Is Syllable Intel (x86) only? How attached is it to the Intel platform? 4.2 What kind of kernel design does Syllable use? 4.3 Does Syllable comply with the POSIX standard? 4.4 Which executable format does Syllable executables and libraries use? 4.5 What filesystem does Syllable use? 4.6 What are file attributes? 4.7 Why does Syllable need a 'special' GRUB? 1. General ========== 1.1 What is Syllable? Syllable is a desktop operating system. The goal of Syllable is to create a reliable and easy-to-use open source Operating System, for the home and small office user. Syllable is currently under development, but it is stable and relatively mature, with a number of useful applications already available. Syllable supports a wide range of common hardware devices, including video, network and sound cards from manufacturers such as Intel, AMD, 3Com, nVidia and Creative. If you would like to see a more comprehensive list of supported hardware, you can search Azaka (http://http://azaka.nutus.com.ar/) 1.2 Where did Syllable come from? Syllable was a fork of Kurt Skauen's AtheOS operating system. 1.3 What happened to Kurt/Atheos? After many years of hacking on AtheOS, Kurt eventually got interested in flying planes, and ended up abandoning working on AtheOS for a lengthy period of time. After months passed with no updates to AtheOS and little sign of future development, a core community of AtheOS devotees forked AtheOS (thanks to AtheOS' GPL license) and started the Syllable project. 1.4 Is it possible to use Syllable in a text-only mode? No, Syllable is designed around its own GUI and cannot support a text-only interface. 1.5 How do I properly shutdown or reboot Syllable? The Syllable Launcher is configured by default to have a "Shutdown" button, and a "Reboot" button. If you wish to Shutdown and power off your computer, click the Shutdown button, or run the "shutdown" command from a shell. If you wish to Reboot your computer, or your computer does not support Advanced Power Management (APM), click the Reboot button. You can also run "reboot" from a shell or press the CTRL+ALT+DEL keys together. Syllable will kill all processes, unmount all filesystems and flush the disk-cache before shutting down or rebooting the machine. The Syllable filesystem (AFS) is journaled, which means that an "unclean" shutdown (E.g. a sudden loss of power) will not corrupt the data on your hard drive, but it may leave you with corrupted files if unwritten data was still held in the disk cache. If you have mounted a Windows (FAT) filesystem during a sudden reboot or shutdown you should validate the disk afterwards (Using E.g. MS-DOS CHKDSK or an equivalent application) to avoid further damage to any data on the disk. 1.6 I have a serial mouse, why doesn't it work? Did you plug the mouse into the first serial port (Commonly known as COM1)? Currently, Syllable only checks the first serial port for a mouse. If you use a serial mouse, you must use the first serial port on your computer. The second serial port (COM2) is used by Syllable for the kernel debugger (even if you don't have a serial cable attached to the port). Ports 3 and 4 are currently not used. Most modern BIOS's allow you to enable, disable, and swap the serial ports on your computer. 1.7 The GUI looks like the Amiga GUI. Is Syllable an AmigaOS clone? No. In the beginning, AtheOS was actualy meant to be one, but these days there is nothing resembling the AmigaOS in Syllable other than the default window borders. Syllable has over half a dozen different window decorators which are installed by default. For example, you may have noticed that many of the screenshots use the "Be" window decorator, which is designed to look a little like the windows in BeOS. 1.8 How do I take a screenshot? Press the "Print Screen" key on your keyboard. The screenshot will be saved to the file /tmp/snapshot.png. Syllable will overwrite this file everytime you press "Print Screen", so if you are taking more than one screenshot, be sure to move or rename each screenshot some before you take the next one. 1.9 How do I get non-English characters to work in the keymap I've set up? Install a font that contains all the necessary characters. Characters above the 7-bit ascii range must be typed as UTF-8 encoded multichars in hex, e.g. the Norwegian "aa" is encoded as the two-byte UTF-8 character(0xc3,0xa5). This gets encoded as 0xc3a5 in the ascii keymap file. 1.10 What do I need to modify in order to support Chinese (Big-5) text? Nothing. All you need to do is to install a font with the required characters, Syllable uses Unicode (UTF-8) encoding. 1.11 How much disk space do I need to install Syllable? The base installation requires at least 150 MB, although that figure may go up or down, depending on the release. You will need another 100 MB or so if you want to install the development tools too. If you have 500 MB to 1 GB to spare you should have enough space to install everything! 1.12 How often are new releases of Syllable? We aim for around 2 months between releases, but sometimes it takes longer. Patch releases (e.g. 0.4.2a) may be released within a week of the original release. 1.13 Where can I find more information about Syllable? You can read the FAQ's and the website here. You might want to check the Wiki pages, in the Documentation Section. There is also the Syllable User Bible, which has a number of tutorials. If your questions are still not answered, you should ask on the mailing list. 1.14 Where can I find software for Syllable? Kamidake lists all known Syllable software. 1.15 The API looks like BeOS. Is Syllable a BeOS clone? No. Syllable is a fork of the AtheOS operating system, originally written by Kurt Skauen. Kurt never intended to copy the BeOS API, in fact AtheOS development started before the first BeBox was shipped. The BeOS API is undoubtedly a good design though. The Syllable API does use a lot of good ideas from the BeOS API, but we also design and add our own classes. 1.16 Does Syllable run under Bochs/VMWare/Virtual PC/...? Yes. See the next section on Emulation. 1.17 What licence is Syllable available under? AtheOS was released under the GPL, and so too is Syllable. Some bits and pieces may be under other free-software licences though. 1.18 How far advanced is Syllable's development? It's resonably mature. It boots, and the kernel is largely complete. 1.19 What are Syllable's system requirements? Syllable requires a processor that supports i586 (Pentium) instructions, this is a leftover from AtheOS; Kurt wrote some lines of i586 instructions in assembler. An installation uses up several hundred megabytes of hard disc. About 20 to 24mb of ram is needed to boot. So, a Pentium 60 with 24mb of ram and a small hard disc should be the minimum currently able to 'run' Syllable. A Pentium 166MMX with 64mb of ram and a 1gb hard drive can run Syllable quite comfortably. PPP is not supported yet, so you can only connect to the internet via a local network at the present time. 1.20 What architectures does Syllable run on? As said above, Syllable is currently hardcoded to require an i586 x86 processor or compatible (it will [to quote Kurt] "crash and burn on a 486"). The current developers are not working on porting Syllable to other platforms or making it a high objective. However, the Syllable code-base is fairly portable as so far as operating systems come. If you wish to develop/maintain a port of Syllable to another system archecture such as PPC or ARM, feel free to do so. 1.21 How can I become involved in development? Are newcomers allowed to join the effort? Sure, just join the Syllable developer mailing list. 2. Emulation. ============= 2.1 Does Syllable run under VMWare? Yes. Syllable runs in VMware 3.x and 4.x for Linux and Windows. AtheOS (which Syllable is based on) runs in VMware 2.x, so it is likely that Syllable also runs in VMware 2.x. Syllable also works in VMware Player 1.x. If you have information about Syllable running or not running in specific VMware versions, please mail Daniel. 2.2 Where can I get a VMware image with Syllable already installed? There is a base install Syllable image pre-installed in a VMware Player image available at http://fprintf.net/syllable/syllablevm.html. Another site which contains recent VMware Player images is http://www.cilinder.be/syllable. VMWare Player images also work in the regular VMware Workstation. In addition, there is an old Syllable 0.4.5 image with developer tools in VMware 4 at syllable.halebob.org. 2.3 Why is my screen messed up in Syllable? VMware 3.2 (and possibly other versions) seem to have problems with the Syllable VESA driver. The only resolution known to work in all situations is 1024x768x32. Some other resolutions are reported to work with some video card/driver combinations of the host OS. As of Syllable 0.5.4 a dedicated VMWare video driver is available, so video should now work fine in all available display modes. There is still a strange issue where parts of the screen are not updated correctly. Moving your mouse over them will update them. 2.4 Does Syllable support the AMD PCNET network card in VMware? Theoretically, yes. There is a driver for this card included with Syllable. There are reports that it does not work with VMware 3.2 for Linux. There are reports that it does work on VMware 3.x for Windows. YMMV. 2.5 Why won't Syllable boot in VMware? VMware assumes that it's Guest OSs do not use memory beyond a certain address (0xf7ffffff to be precise). Ordinarily, Syllable does use this region, which causes it not to boot in VMware. There is a kernel parameter as a work around for this. The kernel parameter is "uspace_end=0xf7ffffff", and needs to be on the end of the kernel line in "/afs/boot/grub/menu.lst". 2.6 Why won't the Syllable ISO images boot in VMware? The Syllable IDE driver (as of 0.5.2) doesn't like having the virtual CD-ROM on the same IDE chain as the virtual hard drive. Put the virtual CD-ROM on IDE 1:0, and the virtual hard drive on IDE 0:0. You will also need to disable DMA disc access. Change your Grub configuration file to something like the following (Changing the disc and partition information to match your installation). The important parts are enable_ata_dma=false and uspace_end=0xf7ffffff: title Syllable root (hd0,0) kernel /atheos/sys/kernel.so root=/dev/disk/ata/hda/0 enable_ata_dma=false \ uspace_end=0xf7ffffff module /atheos/sys/config/kernel.cfg module /atheos/sys/drivers/bus/pci module /atheos/sys/drivers/bus/ata module /atheos/sys/drivers/dev/hcd/ata_pci module /atheos/sys/drivers/fs/afs 2.7 Does Syllable run under Bochs? Yes. Bochs 2.1 added support for High and True colour Vesa graphics when you use the LGPL VGA BIOS. Jan Hauffa previously did some work with Bochs 2.0.1 His website includes a specially patched version of of Bochs 2.0.1 for Windows and instructions on how to install Syllable onto a Bochs virtual hard disk. 2.8 Does Syllable run under Virtual PC? Yes. Syllable runs on Microsoft Virtual PC with very few problems. 2.9 What Virtual PC hardware is supported? The network card is a Digital DS21140 and is supported by the tulip network driver. Audio is a simple SoundBlaster device and is detected by the sbpro driver, although I have not been able to test if this works. The video card is an S3 Trio 32, which is not supported by any of the accelerated graphics drivers but does work with Vesa 2.0. 2.10 What versions of Virtual PC will work? Syllable is known to work on Microsoft Virtual PC 2004 running on Windows 2000 on a Pentium IV machine with 256 MB. Older versions of Connectix Virtual PC (e.g. 5.2) or other versions of Microsoft Virtual PC (e.g. Virtual Server) should also work. We have had reports that Syllable runs under Virtual PC on MacOS (PPC), but this has not been confirmed. If you have more information on what works and what not, please let us know. 2.11 How do I install Syllable under Virtual PC? You can either boot from a real CD with your CD-ROM drive attached to Virtual PC, or you can configure Virtual PC to boot directly from the ISO image. Either way will work, but booting directly from the ISO means you do not need to burn a CD. 2.12 Do you know where I can get a Virtual PC disk image of Syllable? Some Virtual PC disk images of older versions of Syllable have been made available in the past, but unfortunately they are no longer available. If you create a downloadable Virtual PC disk image please let us know! 3. Development ============== 3.1 I have installed the GCC package but whenever I try to compile anything I get the "cannot find binutils" error. GCC needs the GNU assembler and linker to work. This comes in a separate package named "binutils" that you will have to install before using GCC. You can find the "binutils" packege in the download section on this site. 3.2 Can I contribute to the development of Syllable? You can make any improvments to the OS. Just make sure nobody is doing the same as you, and then send a patch to the project manager. 3.3 What documentation is available on porting a Linux driver to Syllable? You can start with the SUB tutorial on Device Drivers. Many people have ported drivers for network interface cards, sound cards and even radio cards. A lot of the current Syllable video drivers are ports of XFree86 video drivers. 3.4 How do I build Syllable from scratch with GCC on a Linux machine? You can't. You must use Syllable to compile Syllable. Even using Syllable, the process is not an easy, so you are advised against it! If you really really want to, you might want to ask for help on the Mailing List. 3.5 I get segfauits when calling libatheos methods, like Desktop().GetResolution(). Why? You can only call libatheos methods from inside an Application class. If you have not created an Application class, or it is not running, your code will segfault when you try to call almost any libatheos method. 3.6 What are the best source-code examples to study for using bitmaps? Take a look at the Xspringies, IconEdit, bmview, or Desktop-manager sources for examples on how to use the os::Bitmap class. Xspringies use a bitmap for "double-buffering" and use the appserver to render into it (by adding a view to the bitmap). IconEdit and bmview copy bitmap-data into the bitmaps themselves and only ask the appserver to render the finished bitmap into an on-screen view. Desktop-manager does both. 3.7 How can I make a Bitmap from a raw pixel data? You can obtain a pointer to the raster-memory by calling the os::Bitmap::LockRaster() member. You can then copy the pixel data directly to that buffer. memcpy( pcBitmap->LockRaster(), pBitmapData, nBitmapSize ); You might have to write your own copy routine if the bitmap data doesn't have the same "pitch" (bytes per row) as the bitmap. To be able to add support for bitmaps allocated in video-memory (to allow manipulating it by the blitter or using it as an video-overlay in the future) there is a method for obtaining the raster-pointer named LockRaster() that returns the pointer and a method named UnlockRaster() that releases it. The application server needs the lock/unlock mechanism to know when it's safe to move the bitmap, if the video-memory it uses is needed by someone else. Kurt plans to change this design slightly, to add a Lock() and Unlock() member that will protect the Bitmap object locally by acquiring a semaphore, and notify the application server so it doesn't move the bitmap between Lock() and Unlock() operations. The LockRaster() and UnlockRaster() will then be removed and a GetRaster() will be added instead. The above example will then look like this: pcBitmap->Lock(); memcpy( pcBitmap->GetkRaster(), pBitmapData, nBitmapSize ); pcBitmap->Unlock(); 3.8 How do you copy raw data into the Bitmap class? The raster-buffer is located in memory that is shared between the appserver and the application, so the application cannot change the raster-pointer. It is legal to write to the pointer returned by os::Bitmap::LockRaster() so you can copy your bitmap-data into the bitmap (see previous answer). Remember to set the os::Bitmap::SHARE_FRAMEBUFFER flag when constructing the bitmap or else os::Bitmap::LockRaster() will always return a NULL pointer. 3.9 How do I make a keymap? Check out this tutorial on SUB. 3.10 OK, I've made a keymap. How do I get it into the distribution? Send it to the mailing list with a quick note telling us about the keymap (E.g. which keyboards and languages it's suitable for) 3.11 What are the differences between the Linux and Syllable driver interfaces? The major driver difference between Syllable and Linux is that in Linux, modules are a part of the kernel that is not yet loaded. In Syllable there is a sharp distinction between the device driver and the kernel. Linux modules can access most of the "internal" kernel structures, e.g. to wait for an event they link nodes into internal scheduler structures, etc. instead of using kernel functions that can abstract the operation. Syllable has a much stricter interface between the kernel and a device driver. The kernel communicates with device drivers through abstract handles rather than internal structures, much like it communicates with applications through file-descriptors, semaphore handles, message port handles, etc. The Syllable kernel has always been pre-emptable. Linux used to allow threads to enter the kernel only one at a time, even after they had added support for SMP. The Linux kernel now allows some concurrency in the kernel, but Linux drivers might still need more semaphore protection added during a port to Syllable. 3.12 Can I test a driver implementation from userspace, or are the syscalls the driver uses only reachable from kernelspace? Many functions are available both in user-space and kernel-space, including the get_pci_info() functions. Some parts of a driver can be tested in user-space, but most of a NIC driver would not lend itself to user-space testing. For example, you can't handle interrupts from user-space, which is a show-stopper for most drivers. At the other end of the spectrum, video drivers are in user space, making use of both x86 port based I/O and PCI memory mapped I/O. If you're not sure what you should and shouldn't do, please ask. 3.13 Why not port Syllable to another kernel? The short answer: It's difficult, and really doesn't give us anything. The long answer: Unlike Linux or traditional Unix systems, Syllable is not a kernel with a GUI on the top, it is an entire system. The GUI relies on the kernel to provide a lot of functionality which it abstracts to the user. Porting the GUI to another kernel would break that abstraction and a lot of the functionality as it is designed. It would also leave us largely at the whim of a third party, and we would need to duplicate a lot of functionality which is already present and working in the Syllable kernel. There is a lot of smart design in Syllable and we would be "throwing the baby out with the bathwater" if we abandoned that design for the small gain of a slightly more mature kernel. 3.14 Why not use X-Windows and X's GUI toolkits? The short answer: Because we don't want to ;) The long answer: The X Windowing system has various technical problems which Syllable seeks to avoid (you probably know what these are). Using X toolkits would be undesirable, as Syllable seeks to be a single, unified system, with its own toolkit. 4. Technical ============ 4.1 Is Syllable Intel (x86) only? How attached is it to the Intel platform? At the moment Syllable will only run on Intel and compatible (e.g. AMD) platforms. That said, most of Syllable is written in highly portable C/C++. There is very little assembly code and none of the internal design is centered around the Intel architecture. Syllable uses a flat paged memory model, and does not depend on "Intel-only" features like segmentation, more than 2 privilige levels, call-gates, etc etc. It is likely that Syllable will also support the AMD x86-64 platform in the future, although no efforts are currently underway to do this. 4.2 What kind of kernel design does Syllable use? As Syllable is a fork of the AtheOS operating system, the author of AtheOS (Kurt Skauen) said "I often ask myself that question too. The kernel is very modular and it has a well-defined interface between the kernel and its device drivers and file systems. Given that each component communicates through a thin, well-defined interface and each component does not know much about the others, it resembles a micro-kernel. I am not sure if this is the right term though, since all kernel components live in kernel-space and are not protected from each other, and these are all properties of a monolitic kernel. I am a bit confused :)" In reality, it is easiest to think of Syllable as a monolithic kernel with modular device drivers. Only high-level functions such as the appserver use the client/server model. 4.3 Does Syllable comply with the POSIX standard? Not fully. 100% POSIX compliance has never been a goal for Syllable but it does support large parts of the standard, including the POSIX threads (pthreads) API. Syllable also uses the GNU libc (Glibc), which means that a large number of POSIX compliant applications can be compiled and run without modification. 4.4 Which executable format does Syllable executables and libraries use? Syllable use ELF (Executable and Linker Format). Unlike many other OS's using ELF the executable image is loaded and handled entirely by the kernel, not through a user space interpreter. Images are loaded on demand and a copy on write (COW) scheme is used so that untouched pages (Those which have not been written to by the application yet) in all images are shared between different instances of the same image when loaded into different processes. 4.5 What filesystem does Syllable use? Syllable uses the AFS filesystem (AtheOS FileSystem). This was also created by Kurt Skauen, as a part of the AtheOS system. It is somewhat similar to the BeOS filesystem. 4.6 What are file attributes? File attributes are streams of data that can be associated to entries (directories, files, symlinks) in the filesystem. Each attribute is associated with a name that must be unique within the file/dir/symlink it is added to. An attribute can hold as much or as little data you want (it have the same size limit's as regular files) and it can contain typed data (int/float/string/ect ect) or just a raw stream of bytes (like an icon image). Attributes are implemented in the native Syllable filesystem but are not entirely used in it yet. It will however be a very important part of the desktop manager where it will be used to keep file/directory specific icons, icon-positions, file-types (the mime-type of a file), etc etc. The desktop manager will use the icon information to visually present the file or directory and it will use the type information to deside what application to launch if a data file of some kind are double-clicked (it will have a data-base with information about what applications handle which mime-types so if you click on a "image/jpeg" type file it will launce a bitmap-viewer, if you click on a file with type "text/plain" it will launce a notepad like text editor, and a "text/x-sourcecode" whould launch a more advanced source-code editor, etc etc. It will also be possible to tell the desktop manager to launch a specific application for any given file or directory independent of it's mimetype by adding an attribute that points to a specific application. It will also be possible to give additional arguments to the launched application by adding them as an attribute of the data file. The concept of attributes comes from BeOS that again have the concept from MacOS. The attributes in BeOS and Syllable have a great advantage over the MacOS "resource fork" in that there can be an unlimited number of them for each file (each identified by a name) and there is no size limit on each attribute. 4.7 Why does Syllable need a 'special' GRUB? Copied from a post on the syllable forum by Vanders: "The problem is that the orignal author of AtheOS, Kurt wrote the AFS filesystem and the AFS module for Grub. Because he wrote the code, he retains the Copyright to it. In order to place the AFS module in the Grub main-line source, the Grub maintainers insist on a Copyright assignment to the FSF. Kurt did not want to do this, so never submitted the AFS module to the Grub maintainers. We cannot submit the module either because we don't own the Copyright on hte code, so we cannot assign it to the Grub maintainers. Unless a third party steps up and re-writes the AFS Grub module and submits it for inclusion themselves, we have to maintain out version of Grub which can read AFS filesystems. - Vanders".