docs: add a bit more stuff

diff --git a/docs/Intro.md b/docs/Intro.md
new file mode 100644 (file)
index 0000000..fc21c5d
--- /dev/null
+++ b/docs/Intro.md
@@ -0,0 +1,50 @@
+# Introduction
+
+## What Is Fuzix
+
+Fuzix is an operating system for eight bit microprocessors, and some bigger
+systems that provides a large subset of the traditional 'Unix like'
+environment including multi-tasking, the ability to execute multiple
+programs at a time.
+
+Fuzix manages your system resources, memory, storage and devices. It
+provides a unified programming interface across many different types of
+machine, as well as providing a consistent but customisable  user interface.
+
+The hardware requirements for Fuzix are small, although higher than those
+for less functional operating systems such as CP/M. The detailed
+requirements are enumerated later in the manual as they vary by platform
+
+## How Does Fuzix Differ From Traditional Unix Systems
+
+Fuzix is derived from Uzi which was itself based upon early Unix ideas from
+between V6 and V7 Unix platforms. Fuzix extends this to reflect more modern
+Posix interfaces for things like terminal handling.
+
+Classic Unix split into two differing strands BSD Unix and SYS5 Unix. Over time
+these were unified by putting every feature of both of them into one large and
+complex system. Fuzix takes a different approach and tries to pick the
+sanest and cleanest interfaces. Generally speaking those are also the ones
+that applications use.
+
+In general Fuzix leans towards System III and early System V, but favours
+POSIX standardised interfaces where possible. Certain nonsensical System V
+misfeatures are deliberately omitted (notably System V IPC). The networking
+interfaces are based upon the BSD socket API rather than the System V
+streams API that nobody ever uses. File locking is via BSD flock() not the
+System V interface because flock is vastly less complex.
+
+The biggest differences are driven by hardware. Most Fuzix systems do not
+have an MMU (memory management unit) so Fuzix does not provide the related
+family of interfaces (mmap, mprotect, munmap etc). Signals related to memory
+protection may also not be generated in hardware but are available at the
+software level.
+
+Eight bit systems have relatively small address spaces so programs that are
+written for mainframe sized memory may not port to Fuzix. Floating point
+hardware is also not usually available so heavy floating point using
+software will not run at any speed. In some cases software can be ported by
+rewriting it not to use stupidly bad algorithms, in other cases the resource
+constraint may be real.
+
+

diff --git a/docs/M68000.md b/docs/M68000.md
index d58ea80..eca4e5d 100644 (file)
--- a/docs/M68000.md
+++ b/docs/M68000.md
@@ -113,3 +113,91 @@ The following binfmt_flat things want fixing ideally
 so the loader and format are likely to change once the platform develops
 further
 
+## Support Code
+
+As well as generic support for the flat memory model C support library code is
+provided in 68000exception.c for exception decoding and signal handling. The
+code understands how to parse 68000/8 and 68010 stack frames, as well as how
+to handle frames up to the MMUless 68020 configuration.
+
+A single routine is provided
+
+    int exception(struct trapdata *framedata)
+
+This processes the passed frame and turns it into a user space signal or an
+exception according to whether it came from kernel or user space. It is
+generally invoked from the exception handlers in the core code, but can also
+be used in any custom handlers as required.
+
+## Assembly Support Code
+
+The 68000 low level code provides the following functions to the C code or
+platform level assembler.
+
+       void *get_usp(void)
+
+       Returns the user mode stack pointer
+
+       void set_usp(void *p)
+
+       Set the user mode stack pointer
+
+       void enable_icache(void)
+
+       Enable the instruction cache if present (68020). A no-op otherwise.
+
+       void flush_icache(void)
+
+       Flush the instruction cache if present (68020). A no-op otherwise.
+
+       void install_vectors(void)
+
+       Install the default trap and exception vector table entries. The
+       reset vector and initial SP are not touched as those addresses are
+       magic on some devices.
+
+       int probe_memory(void *ptr)
+
+       Probes a memory address and returns 0 if the memory does not bus
+       error or one if it catches a bus error. Should be called with
+       interrupts disabled.
+
+       int cpu_type(void)
+
+       Report the CPU type. Current this supports identifying
+       68000/68010/68020. There is partial support for other CPU types
+       but they are not suported by Fuzix yet.
+
+       void dump_registers(void)
+
+       Dump the CPU register state to the debug port
+
+The following routines are available but primarily used directly by the
+flat memory manager
+
+       void copy_blocks(void *dest, void *source, uint32_t num)
+
+       Copies num 512 byte, dword aligned blocks as fast as possible
+       from source to dest, which must not overlap.
+
+       void clear_blocks(void *dest, uint32_t num)
+
+       Clear num 512 byte, dword aligned blocks as fast as possible.
+
+       swap_blocks(void *p1, void *p2. uint32_t num)
+
+       Swap num 512 byte, dword aligned blocks between p1 and p2 as fast
+       as possible.
+
+The following 68000 specific defines are required by the generic code
+
+       DI_MASK: Bits that should be set in SR for 'interrupt disabled'
+
+       EI_MASK: Bits that should be set in SR for 'interrupt enabled'
+
+This can be used to leave interrupts always disabled, or to allow interrupts
+to occur during kernel 'disabled' regions providing those functions do not
+invoke kernel methods. This can be very useful for things like serial port
+servicing where the bytes are queued for receive, or dequeued for send from
+buffers that are emptied or filled on the timer interrupt.
+

diff --git a/docs/Notices.md b/docs/Notices.md
new file mode 100644 (file)
index 0000000..642adb3
--- /dev/null
+++ b/docs/Notices.md
@@ -0,0 +1,36 @@
+# Notices
+
+## Copyright
+
+Fuzix is a copyrighted work. For details of the licensing agreement between
+yourself and the authors please see the COPYING and CREDITS included with
+your installation.
+
+## Disclaimer
+
+NO REPRESENTATION OR WARRNTIES ARE MADE WITH RESPECT TO THE CONTENTS HEREOF
+INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
+PURPOSE. FUZIX IS NOT INTENDED FOR USE IN ANY ENVIRONMENT WHERE ERRORS OR
+MALFUNCTIONS MAY CAUSE A LOSS OF ANY KIND.
+
+## Trademarks
+
+- Amstrad is a trademark of BSkyB plc
+- Apple is a registered trademark of Apple Inc.
+- Atari is a trademark of Atari Interactive Inc
+- CP/M and MP/M are or were a trademark of Digital Research
+- Linux is a registered trademark of Linus Torvalds
+- Microbeee is a trademark of Microbeee Technology
+- Motorola is a trademark of Motorola Trademark Holdings LLC
+- MSX is a trademark of the MSX licensing corporation
+- POSIX is a trademark of the IEEE
+- Rabbit 2000 and Rabbit 3000 are trademarks of Digi International Inc
+- RC2014 is a trademark of Spencer Owen
+- Timex is a registered trademark of Timex Corporation
+- Unix is a registered trademark of The Open Group
+- Z80 and Z180 are trademarks of Zilog Inc
+- ZX Spectrum is a trademark of BSkyB plc
+
+All other trademarks acknowledged.
+
+

diff --git a/docs/index.rst b/docs/index.rst
index ee27553..dc3160b 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,8 @@ Welcome to Fuzix's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   Notices
+   Intro
    Platforms
    DiskFormats
    build-filesystem-ng