diff options
Diffstat (limited to 'share/docs')
| -rw-r--r-- | share/docs/hw/et131x.txt | 215 | ||||
| -rw-r--r-- | share/docs/kernel/ctlfs.md | 125 | ||||
| -rw-r--r-- | share/docs/kernel/disk.txt | 49 | ||||
| -rw-r--r-- | share/docs/lib/liboda.md | 229 |
4 files changed, 618 insertions, 0 deletions
diff --git a/share/docs/hw/et131x.txt b/share/docs/hw/et131x.txt new file mode 100644 index 0000000..43d7c4f --- /dev/null +++ b/share/docs/hw/et131x.txt @@ -0,0 +1,215 @@ +-------------------------------------- +Unofficial ET131X datasheet. If Agere +doesn't give you shit, OSMORA will + +Author: Ian Marco Moffett +-------------------------------------- + +-- PCI information + +VENDOR ID: 0x11C1 (Agere) +Device ID: 0xED00 + +The ET131X exposes its register interface through +PCI BAR 0. + +-- Device register map (register set list) +| +++ GLOBAL REGS (GLOBAL): + // JAGCore register map (offset BAR[0] + 0x0000) + TX_queue_start_addr [dword] (BAR[0] + 0x0000) + TX_queue_end_addr [dword] (BAR[0] + 0x0004) + RX_queue_start_addr [dword] (BAR[0] + 0x0008) + RX_queue_end_addr [dword] (BAR[0] + 0x000C) + PM_CSR [dword] (BAR[0] + 0x0010) + unused [dword] (BAR[0] + 0x0014) + int_status [dword] (BAR[0] + 0x0018) + int_mask [dword] (BAR[0] + 0x001C) + int_alias_clr_en [dword] (BAR[0] + 0x0020) + int_status_alias [dword] (BAR[0] + 0x0024) + sw_reset [dword] (BAR[0] + 0x0028) + slv_timer [dword] (BAR[0] + 0x002C) + msi_config [dword] (BAR[0] + 0x0030) + loopback [dword] (BAR[0] + 0x0034) + watchdog_timer [dword] (BAR[0] + 0x0038) + ---------------------------------------- + NOTES: + [REGISTER INFORMATION] + - TX_queue_start_addr: + Address of transmit queue start in internal RAM. + - TX_queue_end_addr: + Address of transmit queue end in internal RAM. + - RX_queue_start_addr: + Address of receive queue start in internal RAM. + - RX_queue_end_addr: + Address of receive queue end in internal RAM. + - PM_CSR: + Power management control/status register. + - unused: + Not used, leave alone. + - int_status: + Interrupt status register. + - int_mask: + Interrupt mask register + - int_alias_clr_en: + ???? + - int_status_alias: + ???? + - slv_timer: + ???? - for some sort of timeout + - loopback: + Loopback control register + [0x00000001] -> LOOP MAC + [0x00000002] -> LOOP DMA + - watchdog_timer: + Watchdog timer regieter (nanoseconds) +| [0] -> DISABLED +++ MAC REGISTERS (MAC_REGS): + // JAGCore MAC registers (offset BAR[0] + 0x5000) + cfg1 [dword] (BAR[0] + 0x5000) + cfg2 [dword] (BAR[0] + 0x5004) + ipg [dword] (BAR[0] + 0x5008) + hfdp [dword] (BAR[0] + 0x500C) + max_fm_len [dword] (BAR[0] + 0x5010) + reserved1 [dword] (BAR[0] + 0x5014) + reserved2 [dword] (BAR[0] + 0x5018) + mac_test [dword] (BAR[0] + 0x501C) + mii_mgmt_cfg [dword] (BAR[0] + 0x5020) + mii_mgmt_cmd [dword] (BAR[0] + 0x5024) + mii_mgmt_addr [dword] (BAR[0] + 0x5028) + mii_mgmt_ctrl [dword] (BAR[0] + 0x502C) + mii_mgmt_stat [dword] (BAR[0] + 0x5030) + mii_mgmt_indicator [dword] (BAR[0] + 0x5034) + if_ctrl [dword] (BAR[0] + 0x5038) + if_stat [dword] (BAR[0] + 0x503C) + station_addr1 [dword] (BAR[0] + 0x5040) + station_addr2 [dword] (BAR[0] + 0x5044) + NOTES: + [REGISTER INFORMATION] + - cfg1: + First MAC configuration register. + - cfg2: + Second MAC configuration register. + - ipg: + MAC Interpacket Gap configuration register. + - hfdp: + MAC Half Duplex configuration register. + - max_fm_len: + Max packet length (bytes) sent through MAC without + truncation. + - mac_test: + MAC test registers + - mii_mgmt_cfg: + MAC MII Management Config register. + - mii_mgmt_cmd: + MAC MII Management Command register. + - mii_mgmt_ctrl: + MAC MII Management Control register. + - mii_mgmt_stat: + MAC MII Management Status register. + - mii_mgmt_indicator: + MAC MII Management Indicator register. + - if_ctrl: + MAC interface control register. + - station_addr1: + First MAC station address register. + - station_addr2: + Second MAC station address register. + [BITS] + ------------------------------------- + @ cfg1: + [bits 0]: TX enable + [bits 1]: Syncd TX enable + [bits 2]: RX enable + [bits 3]: Syncd TX enable + [bits 4]: TX flow + [bits 5]: RX flow + [bits 7:6]: Reserved + [bits 8]: Loopback + [bits 15:9]: Reserved + [bits 16]: Reset TX func + [bits 17]: Reset RX func + [bits 18]: Reset TX MC + [bits 19]: Reset RX MC + [bits 29:20]: Reserved + [bits 30]: Sim reset + [bits 31]: Soft reset + @ cfg2: + [bits 0]: Full-duplex + [bits 1]: CRC enable + [bits 2]: Pad CRC + [bits 3]: Unused (undefined) + [bits 4]: Length check + [bits 5]: Huge frame + [bits 7:6]: Reserved + [bits 9:8]: Interface mode + [bits 11:10]: Reserved + [bits 15:12]: Preamble + [bits 31:16]: Reserved + @ ipg: + [bits 7:0]: B2B IPG + [bits 15:8]: Minimum IFG enforce + [bits 22:16]: Non B2B IPG 2 + [bits 23]: Unused (undefined) + [bits 30:24]: Non B2B IPG 1 + [bits 31]: Reserved + @ hfdp: + [bits 9:0]: Collision window + [bits 11:10]: Reserved + [bits 15:12]: Re-transmit max + [bits 16]: Excess defer + [bits 17]: No backoff + [bits 18]: BP no backoff + [bits 19]: Alt BEB enable [1] + [bits 23-20]: Alt BEB trunc [1] + [bits 31-24]: Reserved + | + ++ [1]: BEB refers to Binary Exponential Backoff which is + a method to mitigate collisions by doubling the TX + backoff window (throttling TX rate) per collision. + ------------------------------------- + + +------------------------------------------------------------------ +ET131X REGISTER SPACE NOTES: +------------------------------------------------------------------ +[Padding]: + Each register set exists within a 4096 byte region and some + register sets do not fully span that full length. Therefore + when defining the register space within a struct, one must + be sure to account for such gaps by including 'n' bytes of + padding after each register set. Where 'n' is how many bytes + left to fully span 4096 bytes in other words, '4096 - regset_len'. + +------------------------------------------------------------------ +SOFTWARE RESET PROCCESS: +------------------------------------------------------------------ +#define MAC_CFG1_SOFTRST 0x80000000 /* Soft reset */ +#define MAC_CFG1_SIMRST 0x40000000 /* SIM reset */ +#define MAC_CFG1_RESET_RXMC 0x00080000 /* RX MC reset */ +#define MAC_CFG1_RESET_TXMC 0x00040000 /* TX MC reset */ +#define MAC_CFG1_RESET_RXFUNC 0x00020000 /* RX func reset */ +#define MAC_CFG1_RESET_TXFUNC 0x00010000 /* TX func reset */ +#define GBL_RESET_ALL 0x007F /* Global reset */ +------------------------------------------------------------------ +To perform a software reset, one must write the value of MAC_CFG1_SOFTRST, +MAC_CFG1_SIMRST, MAC_CFG1_RESET_RXMC, MAC_CFG1_RESET_TXMC, MAC_CFG1_RESET_RXFUNC, +and MAC_CFG1_RESET_TXMC combined together with a bitwise OR to the 'cfg1' register +of the 'MAC_REGS' register set. + +This results in the MAC core (aka JAGCore) resetting all internal state +and being brought to halt. + +Once the MAC core is reset, you must be sure to also reset the rest of the card, +(I know, just when you thought you were done). This may be done by writing the +value of GBL_RESET_ALL to the 'sw_reset' register of the 'GLOBAL' register set. +This results in the reset of further state such as state machines for TX DMA, RX DMA, +MAC TX, MAC RX, etc cetera. + +To ensure the TX/RX paths of the MAC core are in a known state, one +must write the value of MAC_CFG1_RESET_RXMC, MAC_CFG1_RESET_TXMC, MAC_CFG1_RESET_RXFUNC, +and MAC_CFG1_RESET_TXMC combined together with a bitwise OR to the 'cfg1' register +of the 'MAC_REGS' register set. + +And finally, you must also make sure the 'cfg1' register of the 'MAC_REGS' register +set is also in a known state by clearing it to 0x00000000. diff --git a/share/docs/kernel/ctlfs.md b/share/docs/kernel/ctlfs.md new file mode 100644 index 0000000..3087f60 --- /dev/null +++ b/share/docs/kernel/ctlfs.md @@ -0,0 +1,125 @@ +# The Hyra control filesystem (ctlfs) + +Written by Ian M. Moffett + +## Rationale + +Historically, Operating Systems of the Unix family typically relied +on syscalls like ``ioctl()`` or similar to perform operations (e.g., making calls through a driver) +via some file descriptor. Let's say for example, one wanted to acquire the framebuffer +dimensions of a given framebuffer device. To start, they'd acquire a file descriptor +by calling ``open()`` or similar on it. Then they'd make their ``ioctl()`` call. + +```c +int fd = ...; + +ioctl(fd, IOCTL_FBINFO, &fb_info); +... +``` + +While this works fine and is relatively simple to use from the user's +perspective, it is very clunky when you pop the hood and peer into the +inner-workings of it within the kernel. The number of possible requests +that can be passed through a file descriptor can grow quite rapidly which +can require really large switch statements within the drivers that implement +an ``ioctl()`` interface. + +## Replacing ``ioctl()`` + +Hyra provides ctlfs, an abstract in-memory filesystem designed for +setting/getting various kernel / driver parameters and state via +the filesystem API. The control filesystem consists of several +instances of two fundamentals: "control nodes" and "control entries". + +### Control nodes + +Control nodes are simply directories within the ``/ctl`` root. For example, +console specific control files are in the ``/ctl/console`` node. + +### Control entries + +Control entries are simply files within specific control nodes. For example +console features may be find in the ``consfeat`` entry of the ``console`` node +(i.e., ``/ctl/console/consfeat``). + +See ``sys/include/sys/console.h`` and ``sys/fs/ctlfs.h`` for more +information. + +## The ctlfs API + +The Hyra kernel provides an API for subsystems and drivers +to create their own ctlfs entries and nodes. This may be found +in sys/include/fs/ctlfs.h + +### Control operations + +Each control entry must define their own set of +"control operations" described by the ``ctlops`` structure: + +```c +struct ctlops { + int(*read)(struct ctlfs_dev *cdp, struct sio_txn *sio); + int(*write)(struct ctlfs_dev *cdp, struct sio_txn *sio); + ... +}; +``` + +NOTE: Callbacks defined as ``NULL`` will be +ignored and unused. + +## "Meow World": Creating a ctlfs entry + +```c +#include <sys/types.h> +#include <sys/sio.h> +#include <fs/ctlfs.h> + +static const struct ctlops meow_ctl; + +/* + * Ctlfs read callback - this will be called + * when "/ctl/meow/hii" is read. + */ +static int +ctl_meow_read(struct ctlfs_dev *cdp, struct sio_txn *sio) +{ + char data[] = "Meow World!"" + + /* Clamp the input length */ + if (sio->len > sizeof(data)) { + sio->len = sizeof(data) + } + + /* End of the data? */ + if ((sio->offset + sio->len) > sizeof(data)) { + return 0; + } + + /* Copy the data and return the length */ + memcpy(sio->buf, &data[sio->offset], sio->len); + return sio->len; +} + +static int +foo_init(void) +{ + char ctlname[] = "meow"; + struct ctlfs_dev ctl; + + /* + * Here we create the "/ctl/meow" node. + */ + ctl.mode = 0444; + ctl.devname = devname; + ctlfs_create_node(devname, &ctl); + + ctl.ops = &fb_size_ctl; + ctlfs_create_entry("attr", &ctl); + return 0; +} + +static const struct ctlops meow_ctl = { + .read = ctl_meow_read, + .write = NULL, +}; +``` diff --git a/share/docs/kernel/disk.txt b/share/docs/kernel/disk.txt new file mode 100644 index 0000000..4b7f6e5 --- /dev/null +++ b/share/docs/kernel/disk.txt @@ -0,0 +1,49 @@ +======================================= + Device filesystem (/dev) interface +======================================= + + USER + / \ + /dev/sd0, /dev/sd1 + / \ + namei() namei() + / \ + vop() vop() + / \ + driver driver + / \ + HARD DRIVE 0 HARD DRIVE 1 + +======================================= + Hyra disk engine framework +======================================= + USER + | + HDEI [ hyra disk-engine interface: like disk_io() ] + kernel -- | + HDE [ hyra disk engine: drives the core disk logic ] + | + HDF [ hyra disk framework (core logic) ] + / \ + HARD DRIVE 0 HARD DRIVE 1 + + + [DRIVER] <-> [DISK ENGINE] + ^ + | + V + [ SLS / FILESYSTEM] + ^ + | + V + [USER] + + + NOTES: + + - Unix filesystem-like strucuture with indirection + for orthogonally persistent objects + + - Explicit storage lifetime (i.e., persistent or ephemeral) + during allocation at a page-level granularity + diff --git a/share/docs/lib/liboda.md b/share/docs/lib/liboda.md new file mode 100644 index 0000000..e5345a4 --- /dev/null +++ b/share/docs/lib/liboda.md @@ -0,0 +1,229 @@ +# The OSMORA Display Architecture (ODA) + +Written by Ian M. Moffett + +## Introduction + +The OSMORA Display Architecture (ODA) is a protocol describing how +a compositor should create and manage graphical windows. A graphical +session in Hyra consists of a compositor, window management system and +management of user input. + +There are many existing display architectures out there. Take for instace, the X11 +protocol. X11 for example, has the concept of an "X server" in which window managers +or certain graphical programs would connect to as a means of performing interprocess +communication (IPC). The idea is that X will service graphics related requests from +the window manager or compositor. + +While this works just fine, the highly centralized nature of X11 or similar protocols +may complicate the flexibility of the graphics stack. On the other hand with ODA, a +compositor links with the ODA library and becomes the server for window managers running +on the system. The idea of ODA is to minimize complexity while preserving flexibility. + +Additionally, the compositor should provide its own API for use by window management +software. + +## Scope + +This document serves to describe common OSMORA Display Architecture (ODA) concepts +as well as providing basic example C sources showcasing how compositors and window +managers may interface with the described APIs for various needs. + +## Terminology + +### OSMORA Display Architecture (ODA): + +OSMORA protocol defining common interfaces for C2W and +W2C interactions. + +### Compositor to window (C2W): + +Describes the direction of communication originating from +a compositor and directed towards a specific window: + +``COMPOSITOR -> WINDOW`` + +### Window to compositor (W2C): + +Describes the direction of communication originating from +a specific window to a compositor running on the system: + +``WINDOW -> COMPOSITOR`` + +## Architecture + +``` ++-------------+ +| LIBGFX | ++-------------+ + ^ + | linked with libgfx + V ++-------------+ +| COMPOSITOR | ++-------------+ <---+ signal + | | | | + | | | | c2w: <winop: e.g., close> + | | | | w2c: <winop to accept: e.g., close> + WIN WIN WIN <---+ +``` + +### C2W signal flow: + +``` +-- CLOSE SIGNAL EXAMPLE -- + +WINDOW RECEIVES CLOSE SIGNAL + | + ECHO BACK TO COMPOSITOR + | + YES ---+--- NO + | | + | V + | nothing happens + | + V + window is destroyed by compositor +``` + +## Libgfx + +The Hyra userspace includes ``libgfx`` which is a low-level graphics library aimed +to facilitate drawing on the screen and performing various graphical operations while +decoupling from the concept of compositors, windows and the ODA as a whole. In other words, +libgfx has no knowledge of anything outside of the framebuffer and itself. + +The following is an example of how one may draw a yellow square at +x/y (30,0): + +```c +#include <libgfx/gfx.h> /* Common routines/defs */ +#include <libgfx/draw.h> /* Drawing related routines/defs */ + +int +main(void) +{ + struct gfx_ctx ctx; + struct gfx_shape sh = GFX_SHAPE_DEFAULT; + int error; + + /* Set the x/y and color */ + sh.x = 30; + sh.y = 0; + sh.color = GFX_YELLOW + + error = gfx_init(&ctx); + if (error < 0) { + printf("gfx_init returned %d\n", error); + return error; + } + + /* Draw the square and cleanup */ + gfx_draw_shape(&ctx, &sh); + gfx_cleanup(&ctx); + return 0; +} +``` + +## Liboda + +The Hyra userspace includes the ``liboda`` library which includes various +interfaces conforming to the OSMORA Display Architecture (ODA). + +### Linking a compositor with liboda + +In order for an ODA compliant compositor to reference library +symbols for ``liboda``, it should use the following linker flags: + +``... -loda -logfx`` + +### ODA Session + +For the ODA library to keep track of state, it relies on an ``oda_state`` +structure defined in ``liboda/oda.h``. Additionally, in order for any ODA +library calls to be made, the compositor must initialize the library with +``oda_init()`` like in the following example: + +```c +#include <liboda/oda.h> + +struct oda_state state; +int error; + +/* Returns 0 on success */ +error = oda_init(&state); +... +``` + +Upon failure of ``oda_init()`` a negative POSIX errno value +is returned (see ``sys/errno.h``). + +### Using liboda to request windows + +A compositor may request windows from the ODA by using +``oda_reqwin()`` like in the following example: + +```c +#include <liboda/oda.h> + +... +struct oda_wattr wattr; +struct oda_state state; + +... + +wattr.session = &state; +wattr.parent = NULL; +wattr.bg = GFX_YELLOW; +wattr.x = 200; +wattr.y = 150; +wattr.w = 120; +wattr.h = 300; + +/* Returns 0 on success */ +error = oda_reqwin(&wattr, &win); +``` + +Arguments passed to ``oda_reqwin()`` are first stored in a ``struct oda_wattr`` +structure to minimize the number of parameters used in the function signature. + +Upon failure of ``oda_reqwin()`` a negative POSIX errno value +is returned (see ``sys/errno.h``). + +### Input management + +The liboda library additionally provides an input API that facilitates +management of user input (e.g., keyboard). + +(See ``liboda/input.h``) + +#### The ``oda_key`` structure + +ODA provides a standard description of keys received from a keyboard +device. Keyboard input is represented by the ``oda_key`` structure shown +below: + +```c +struct oda_key { + uint16_t type; + uint8_t scancode; + char ch; + ... +}; +``` + +The ``type`` field describes the key type, valid key types can be +found within the ``ODA_KEY_*`` definitions in ``liboda/input.h``. + +The ``scancode`` field contains the raw keyboard scancode received +from the device. + +The ``ch`` field contains the ASCII representation of the input received +from the device. + +#### The ``oda_kbd`` structure + +ODA represents keyboard devices through the ``oda_kbd`` structure found +in ``liboda/input.h``. This structure contains callbacks that are set up +by the compositor to be invoked when their respective keyboard related +event occurs. |