{"id":24383944,"url":"https://github.com/schuylermartin45/seegol","last_synced_at":"2025-04-11T01:45:49.079Z","repository":{"id":151366896,"uuid":"74838193","full_name":"schuylermartin45/seegol","owner":"schuylermartin45","description":"Master's Thesis Project: Shoyler's Extremely Experimental Graphical Operating Library (SeeGOL)","archived":false,"fork":false,"pushed_at":"2020-07-16T23:06:56.000Z","size":5372,"stargazers_count":7,"open_issues_count":13,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T22:51:24.976Z","etag":null,"topics":["gcc","graphics-library","operating-system","qemu","vga"],"latest_commit_sha":null,"homepage":"https://shoyler.com/html/projects.html","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schuylermartin45.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-11-26T16:47:38.000Z","updated_at":"2024-04-27T14:29:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"6f130632-a8d4-44e6-86d4-a16d963242ca","html_url":"https://github.com/schuylermartin45/seegol","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schuylermartin45%2Fseegol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schuylermartin45%2Fseegol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schuylermartin45%2Fseegol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schuylermartin45%2Fseegol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schuylermartin45","download_url":"https://codeload.github.com/schuylermartin45/seegol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248327862,"owners_count":21085258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gcc","graphics-library","operating-system","qemu","vga"],"created_at":"2025-01-19T10:45:00.763Z","updated_at":"2025-04-11T01:45:49.056Z","avatar_url":"https://github.com/schuylermartin45.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HSC: Shoyler's Extremely Experimental Graphical Operating Library - SeeGOL\n#### Author:  Schuyler Martin \u003csam8050@rit.edu\u003e\n\n![alt tag](/media/hsc.png)\n\n\n## About\nSeeGOL (pronounced _sea-gull_) is my final graduate project. The end goal is to\ndevelop a graphics library/windowing system to 16-bit x86 processors (i386 and\nabove).\n\n### Original Plan\nI originally wanted to develop a library for the IBM PCjr. That has proven to\nbe too difficult using modern tools. There is a branch, `pcjr_8086_compat`,\nwhich includes my attempt at converting gcc's i386 assembly to only valid\ninstructions on the 8086.\n\n#### Notes on the PCjr\nThe PCjr model I have has 128kb of RAM and a 3.5in floppy drive that can only\nread the older \"1mb\" IBM floppy format (as opposed to the much more common\n2.44mb format most people are probably familiar with).\n\n\n## Setup\nSeeGOL was originally built on a Fedora 24 workstation using gcc 6.3.1.\nAlthough it should be able to be built on almost any reasonable Linux system,\nI have run into issues with the custom image compression Python scripts running\noff of older versions of the Python 3 interpreter on Debian.\n\nThe Makefile is configured to warn and error-out on missing software build\ndependencies.\n\n### Dependencies\nThese programs are necessary to build and install \n- dd\n- make\n- makedepend\n- Python +3.5 (a Python 3 script is used to compress image data before being\n  added to SeeGOL. It should work with any version of Python 3 but I did have\n  the script crash once on a Debian machine running Python 3.4)\n- ImageMagick (the `convert` program is used to down-sample image files)\nAn emulator (such as QEMU) may also be helpful in running the OS.\n\n### Compiling from Source\nTo compile all of the x86 and C files and put them into a single flat binary:\n```shell\nmake see_gol\n```\nTo build the complete OS image, targetted to boot from a floppy:\n```shell\nmake floppy.img\n```\nTo remove all binaries and OS images:\n```shell\nmake clean\n```\n\n### Running with QEMU\nThere is a provided bash script so that the OS can be easily run with QEMU\n```shell\n./tools/i386_qemu.sh\n```\n\n### Running with Physical Hardware\nAssuming the floppy is mounted at `/dev/fd0` (which is common on Linux systems)\nsimply run:\n```shell\nmake floppy\n```\nOtherwise dd the image file to the floppy:\n```shell\ndd if=/path/to/floppy.img of=/path/to/floppy\n```\n\nTo just build the floppy image:\n```shell\nmake floppy.img\n```\n\nSimilarly, `usb.img` and `usb` make directives also exist. `usb` assumes the\ndrive is at `/dev/sdj` (because that's the location my college desktop used).\n\nAfter making any necessary changes to the boot order via a machine's BIOS\nsettings, SeeGOL should be bootable from this floppy on almost any Intel x86\ncomputer. Modern machines that do not have a floppy drive can usually boot\nSee warning notes below for further information.\n\n### Warnings\nObviously this project comes without any warranties. The software provided has\nnot been extensively tested across all possible hardware configurations.\nAlthough unlikely, since this OS does interact directly with the hardware, it\ncould potentially damage it.\n\nRun at your own risk.\n\n#### Note on running this project on anything that isn't a PCjr\nAlthough SeeGOL should run on any x86 system created after the PCjr (the x86\narchitecture is \"backwards compatible to the dawn of time\"), SeeGOL is not\nguaranteed to run properly on anything other than the PCjr. The main concern is\nthat the PCjr uses the CGA graphics chip, as opposed to the much more common\nVGA chip. Most modern graphics cards, on-processor graphics chips, and\nemulators provide backwards-compatibility support for VGA. Although CGA and VGA\nboth come from IBM and work in similar ways, VGA is not a direct descendant of\nCGA. Therefore the OS may not appear like it does on the PCjr across all\nsystems or it may not work at all.\n\n\n## Directories\nHere is a quick description of the top-level directories. Some of these\ndirectories have their own READMEs.\n\n### bin/\nStores binary objects (compiled code).\n\n### dgb_bin/\nStores compile-time debugging information. These are files that list the source\ncode and compiled assembly instructions together with memory addresses.\n\n### docs/\nExtensive documentation and presentations on the project.\n\n### img/\nStores the image files that can be dd'd to storage media and used to boot the\nOS.\n\n### media/\nContains media content not directly packaged into the OS.\n\n### old/\nDeprecated code that is kept around as reference material.\n\n### src/\nSource code directory for the project.\n\n### tools/\nIncludes scripts and other helpful tools used to run and debug the OS.\n\n\n## User Manual\nSeeGOL comes with a built-in user manual. A help menu is accesible from both\nthe main GUI menus and from SeeSH (the SeeGOL SHell).\n\n\n## Design\nFor a complete design overview, please see the docs/ directory.\n\n\n## Rolling Status Log\nThis a higher-level discussion of the project status while in development.\n\n### January 4th, 2017\n- I decided to make the project public. I was going to wait until more had been\n  completed but enough people have seemed interested in seeing what I had done\n  that I figured I would publicly show my progress.\n- I have booted SeeGOL on three platforms so far:\n  - Modern x86 System (1st generation Core Series): Main function is reached\n    but some functions defined outside of the main C file do not execute.\n  - QEMU: Same behavior as with the physical x86 machine.\n  - PCjr: Everything written in x86 assembly works. Nothing happens when the\n    code written in C executes (more on that below).\n- gcc does not compile to true 16-bit x86. Modern x86 systems will accept and\n  run many 32-bit instructions in real mode despite not being in protected\n  mode. To get around this, I think I may switch to using the \"Amsterdam\n  Compiler Kit\" which claims it can compile to use only 16-bit instructions. If\n  this does not work, I might be stuck writing some plugins for gcc.\n\n### January 17, 2017\n- I am (for now) giving up on targeting the PCjr as the primary platform for\n  this project. I can not find or implement a reliable tool set that will\n  compile C to 8086 assembly. I will now be targeting i386 processors instead.\n  SeeGOL should be able run on almost any modern x86 machine in Real Mode.\n\n### February 1, 2017\n- I just solved a major bug with the kernel. It appears as though there is a\n  difference between the `.code16` and `.code16gcc` assembly directives. The\n  former causes strange stack behavior and my best guess is that gcc is not\n  properly handling segmentation addressing based on the initialization\n  process in the bootloader. I can't find any documentation online that\n  describes the directives but it makes a clear difference. I can now write\n  messages to text video. I plan to improve the I/O tools shortly and then\n  move to starting my work with the graphics modules.\n\n### February 13, 2017\n- My graphics work from the Systems Programming class has been imported and\n  significantly improved. Right now only Mode13h is supported but I have laid\n  out the groundwork for other graphics modes. User programs (installed via the\n  SeeSH shell interface) must access the graphics hardware through the Graphics\n  Library (GL) package. This is actually enforced by design, unlike my work in\n  Sys Prog.\n\n### February 27, 2017\nA few major bugs/realizations came out of this past weekend, while laying the\nground work for SeeGOL's image drawing capabilities.\n- gcc's 16-bit compilation process does not use the segment registers. I\n  previously thought that I was able to address 20 bits of memory (up to the\n  A20 gate, 1mb barrier) but that is not the case. Since gcc does not manage\n  the segment registers in Real Mode; I only have 64kb of memory to work with.\n  I found this out the hard way while developing the image drawing code in the\n  GL package, running out of memory while trying to import XPM files.\n- XPM is a file format developed for X11 that stores image data as an indexed\n  array of byte data. The file format is C code; you can simply include the\n  file and to access an array of strings, each character byte representing a\n  a value in a color look-up table. This would be an ideal image format for\n  SeeGOL, as the image data can be baked into the OS, without the need of a\n  reading image files...which would require a file system...that I don't have.\n- However in my initial testing I found that the XPM file format is not space\n  efficient...and ate up all my text memory. So I came up with a modified\n  version of XPM: CXPM, Compressed X Pixel Map (the first proprietary element\n  in SeeGOL that isn't prefixed with 'See'). To save space, the CXPM format is\n  limited to less than 16 colors (each byte represents 2 pixels, identified\n  by 4 bits) and then Huffman encoded in one dimension, per scanline. The\n  run-length encoding greatly reduces the space used since so few colors are\n  used. The full details of the spec are described currently in the `cxpm.py`\n  file under `src/res/`. The spec may be further modified and I hope to write\n  an OpenCV program that will quantize images and write them to the CXPM\n  program, further automating the process. Currently I'm relying on Gimp and\n  a Python script to convert color-quantized images to XPM and then to CXPM.\n- One major (and painful to figure out) bug I ran into is that Python3 defaults\n  to encoding strings in UTF-8. UTF-8 is a variable length encoding scheme and\n  when I initially created CXPM files, it looked like text information was\n  being saved correctly (confirmed through vim, less, cat, etc). However, when\n  I compiled my code, I noticed that extra color information was being added to\n  my test image, causing the images to \"bleed out\" of frame. Turns out that\n  the UTF-8 encoding scheme was putting the extra bytes in my C strings and I\n  was trying to interpret those bytes as color. To solve this issue, I switched\n  the encoding scheme to 'latin-1', which is a fixed length 8-bit encoding\n  scheme...so when I write 8 bits of bit-packed color information in Python,\n  I get 8 bits and not occassionally 16 bits.\n\n### February 28, 2017\n- After talking with a friend, I realized that there was no reason that CXPM\n  needed to store pixel information in strings. I have now re-worked the format\n  to store unsigned bytes instead of characters. This simplifies the encoding\n  and decoding process and, in the process, solved multiple issues with\n  encoding and decoding the image data as characters. I can now use 0 as a\n  marker (i.e. the NULL byte) and I don't have to deal with issues in using\n  newline characters (byte value of 10) in the string code. tl;dr I can store\n  more color information while speeding up the decoding process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschuylermartin45%2Fseegol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschuylermartin45%2Fseegol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschuylermartin45%2Fseegol/lists"}