DirtOS notes

IMPORTANT always use an external power source that can supply at least 10W!
I had MMC (SD card) detection issues in u-boot when I ran my Cubieboard2 off just the micro-USB port.

Allwinner A20 (Cubieboard2)

use u-boot config Cubieboard2_defconfig
I don't have a suitable power connector for this board, so I've switched to my A10 board for now.

Allwinner A10 (OLinuXino Lime)

u-boot

1. choose a release
   • versions >= 2015.10 needed for boot over USB
   • versions > 2017.01 blew up while building due to libfdt or something
   • versions >= 2018.01 require GCC >= 6.0
   • so, version 2017.01 seems good
2. download
   1. wget "ftp://ftp.denx.de/pub/u-boot/u-boot-2017.01.tar.bz2" (about 12MB in size)
   2. wget "ftp://ftp.denx.de/pub/u-boot/u-boot-2017.01.tar.bz2.sig"
   3. gpg --verify --keyring ./uboot-keyring.gpg ./u-boot-2017.01.tar.bz2.sig
3. extract
   1. tar xf u-boot-2017.01.tar.bz2
   2. cd u-boot-2017.01
4. configure
   1. make CROSS_COMPILE=arm-none-eabi- A10-OLinuXino-Lime_defconfig
      • configurations can be listed with ls ./configs/
5. build
   1. install build-essential, arm-none-eabi toolchain, bc, device-tree-compiler
   2. make CROSS_COMPILE=arm-none-eabi- -j4
6. test
   1. connect the USB serial device to the Allwinner device
      • only connect the TX, RX, and GND lines, do not connect the power line!
      • connect USB serial TX to Allwinner RX
      • connect USB serial RX to Allwinner TX
   2. screen /dev/ttyUSB0 115200
   3. sunxi-fel uboot ./u-boot-sunxi-with-spl.bin
   4. check for u-boot messages in the serial console

OEM u-boot image for the Cubieboard2 is here but it's really old (2014.01-rc1-09154-gfb357b4)

fun u-boot commands:

• gpio set PH2 - turn on LED1
• gpio clear PH2 - turn off LED1

USB

prerequisites:

• USB serial
  1. only use a USB serial device with 3.3v line levels!
     • check the TX pin with a multimeter (it idles high)
       • make sure the TX pin is not connected to anything
  2. add your user to the uucp group
     • sudo usermod --append --groups uucp $(whoami)
  3. create udev rule
     1. plug in USB serial device
     2. check USB serial device name
        1. dmesg | grep -i "tty"
     3. sudo ${EDITOR} /etc/udev/rules.d/80-usbserial.rules
        • SUBSYSTEM=="usb", KERNEL=="ttyUSB*", GROUP="uucp", MODE="0660"
          • where ttyUSB is whatever was found with dmesg previously
  4. restart udev service
  5. unplug USB serial device, plug it back in
  6. test
     1. install serial console program (screen, minicom, etc)
     2. try running the serial console program with the USB serial device without sudo
        • example: screen /dev/ttyUSB0 115200
• sunxi-fel
  1. get sunxi-tools
     1. download
        1. git clone https://github.com/linux-sunxi/sunxi-tools
     2. build
        1. install build-essential
        2. cd sunxi-tools
        3. make
  2. USB permissions
     1. add your user to the uucp group
        • sudo usermod --append --groups uucp $(whoami)
     2. get sunxi device's USB ID
        • lsusb
          • Bus 042 Device 021: ID 1f3a:efe8
     3. create udev rule
        • sudo ${EDITOR} /etc/udev/rules.d/81-sunxi.rules
          • SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8", GROUP="uucp", MODE="0660"
     4. restart udev service
     5. unplug sunxi device, plug it back in
  3. test
     1. sunxi-fel version
        • AWUSBFEX soc=00165100(A20) 00000001 ver=0001 44 08 scratchpad=00007e00 00000000 00000000

steps:

1. set up the board to boot into FEL mode
   • don't use a board with NAND
     • maybe a blank NAND would work
   • remove any SD cards
2. connect USB
3. send u-boot
   • u-boot only
     • sunxi-fel uboot ./u-boot-sunxi-with-spl.bin
   • u-boot with Linux kernel
     • sunxi-fel -v uboot u-boot-sunxi-with-spl.bin write 0x42000000 uImage write 0x43100000 boot.scr
       • TODO confirm this

SD

layout (from sunxi wiki):

• at 0x00000, size 0x02000: MBR
• at 0x02000, size 0x08000: SPL
  • size may only be 0x06000 (see this commit)
• at 0x0A000, size 0x7E000: u-boot
• at 0x88000, size 0x20000: environment (for u-boot?)
• at 0xA8000, size 0x20000: u-boot falcon mode boot parameters
• at 0xC8000, size 0x38000: u-boot falcon mode kernel
• at 0x100000: storage partitions

formatting steps:

1. clear the beginning of the SD card
   1. sudo dd if=/dev/zero of=${SDCARD} bs=1M count=4
2. partition the SD card
   1. sudo parted ${SDCARD}
      1. mklabel msdos
      2. mkpart primary fat32 1M 100%
         • 1M value comes from the layout table above
      3. quit
3. format the partition
   1. sudo mkfs --type vfat -F 32 ${SDCARDp1}
4. write u-boot to the SD card
   1. sudo dd if=./u-boot-sunxi-with-spl.bin of=${SDCARD} bs=1K seek=8
5. flush disk cache
   1. sync
6. check that the FAT32 partition wasn't clobbered
   1. sudo fsck -t vfat -M -N ${SDCARDp1}
7. eject SD card

linux stuff:

• uImage (kernel with a u-boot wrapper)
  • TODO use mkimage
    • mkimage -A arm -O linux -T kernel -C none -a 0x42000000 -e 0x42000000 -n "name" -d kernel.bin uImage
• boot.scr (boot script in binary format)
  1. write a boot.cmd script (example)
  2. mkimage -C none -A arm -T script -d ./boot.cmd ./boot.scr
     • TODO confirm this

• file format
  • ELF?
• loading
  1. kernel loads code section
  2. kernel links all dangling function references to API calls into itself
     • system calls are just function calls
     • similar to loading a program which uses dynamic linking
• program files can have embedded data
  • example
    • graphics
    • sound
    • maps
  • allows for single-file distribution
  • only code section is loaded on execution
    • no RAM penalty
    • load embedded data whenever
• programs that only call API functions should execute on all hardware with the same CPU
  • TODO name is "universal program"?
  • except for sys API, of course

Key to Flags:
  W (write), A (alloc), X (execute), M (merge), S (strings), I (info),
  L (link order), O (extra OS processing required), G (group), T (TLS),
  C (compressed), x (unknown), o (OS specific), E (exclude),
  y (purecode), p (processor specific)

static ELF, not stripped

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .text.startup.mai PROGBITS        40000000 010000 000088 00  AX  0   0  4
  [ 2] .rodata.main.str1 PROGBITS        40000088 010088 000008 01 AMS  0   0  4
  [ 3] .debug_info       PROGBITS        00000000 010090 00033c 00      0   0  1
  [ 4] .debug_abbrev     PROGBITS        00000000 0103cc 0001d5 00      0   0  1
  [ 5] .debug_loc        PROGBITS        00000000 0105a1 000081 00      0   0  1
  [ 6] .debug_aranges    PROGBITS        00000000 010622 000030 00      0   0  1
  [ 7] .debug_ranges     PROGBITS        00000000 010652 000048 00      0   0  1
  [ 8] .debug_line       PROGBITS        00000000 01069a 000083 00      0   0  1
  [ 9] .debug_str        PROGBITS        00000000 01071d 00026a 01  MS  0   0  1
  [10] .comment          PROGBITS        00000000 010987 00001a 01  MS  0   0  1
  [11] .ARM.attributes   ARM_ATTRIBUTES  00000000 0109a1 00003b 00      0   0  1
  [12] .debug_frame      PROGBITS        00000000 0109dc 000044 00      0   0  4
  [13] .symtab           SYMTAB          00000000 010a20 000130 10     14  18  4
  [14] .strtab           STRTAB          00000000 010b50 000013 00      0   0  1
  [15] .shstrtab         STRTAB          00000000 010b63 0000c1 00      0   0  1

static ELF, stripped

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .text.startup.mai PROGBITS        40000000 010000 000088 00  AX  0   0  4
  [ 2] .rodata.main.str1 PROGBITS        40000088 010088 000008 01 AMS  0   0  4
  [ 3] .comment          PROGBITS        00000000 010090 00001a 01  MS  0   0  1
  [ 4] .ARM.attributes   ARM_ATTRIBUTES  00000000 0100aa 00003b 00      0   0  1
  [ 5] .shstrtab         STRTAB          00000000 0100e5 00004b 00      0   0  1

• kernel, user programs both run at maximum modes
• user programs may directly access hardware
  • not recommended, though
  • calls to sys functions mark a program as not universal
• MMU is enabled
  • mostly for verifying code correctness
    • TODO put unused page "barriers" between each allocated block to detect array out of bounds?
  • no virtual memory/paging/swap

ARMv7

• NEON required
  • it's mandatory on all ARM v7 CPUs except the Cortex-A5 and Cortex-A9
  • useful for 2D graphics, etc
  • TODO 128bit vs 64bit
    • Cortex-A5,-A7,-A8,-A9: 64bit
      • most easily available SoCs are A7, A8, or A53
    • Cortex-A12,-A15,-A17: 128bit
  • NEON code is optional for user programs
• FPU required ("hardfloat" compiler)
  • it's mandatory on all ARM v7 CPUs except the Cortex-A5 and Cortex-A9
  • useful for 3D graphics, etc
  • TODO target VFPv3 when building for ARMv7 (is VFP v4 backwards compatible with v3?)
    • Cortex-A8: VFPv3
    • pretty much everything else: VFPv4
  • hardfloat code is optional for user programs

ARMv8

• NEON and FPU are mandatory on all ARM v8 CPUs
  • TODO NEON types
  • TODO VFP types

ARM machines that might have vsync interrupt support:

• Zynq: ./hw/display/xlnx_dp.c:1159: xlnx_dpdma_trigger_vsync_irq(s->dpdma);
  • xilinx-zynq-a9
• OMAP2: ./hw/display/omap_dss.c:119: s->rfbi.vsync = 0; and ./hw/display/blizzard.c:218: s->vsync = 1;
  • n800
  • n810
• PXA2xx: ./hw/display/pxa2xx_lcd.c:904: qemu_irq_raise(s->vsync_cb);
  • connex
  • borzoi
  • tosa
  • mainstone
  • terrier
  • akita
  • z2
  • spitz
  • verdex

PXA270 looks to be the best supported

might as well cherry-pick useful API calls from existing OSs/kernels

MS-DOS API

from the MS-DOS API Wikipedia article and Barry ???

• 20h - Terminate program - NO, return from main() instead
• 21h - Main DOS API
  • 00h - Program terminate - NO, return from main() instead
  • 01h - Character input - YES, serial comms only
  • 02h - Character output - YES, serial comms only
  • 03h - Auxiliary input - NO, no aux device
  • 04h - Auxiliary output - NO, no aux device
  • 05h - Printer output - NO, no printer
  • 06h - Direct console I/O - NO, no console
  • 07h - Direct console input without echo - NO, no console
  • 08h - Console input without echo - NO, no console
  • 09h - Display string - YES, serial comms only
  • 0Ah - Buffered keyboard input - NO, no console
  • 0Bh - Get input status - NO, no console
  • 0Ch - Flush input buffer and input - NO, no IO buffers
  • 0Dh - Disk reset - NO, no direct disk control
  • 0Eh - Set default drive - NO
  • 0Fh - Open file - YES
  • 10h - Close file - YES
  • 11h - Find first file - YES?, would prefer "get all files in dir"
  • 12h - Find next file - NO
  • 13h - Delete file - YES
  • 14h - Sequential read - YES, read file
  • 15h - Sequential write - YES, write file
  • 16h - Create or truncate file - NO, part of file open
  • 17h - Rename file - YES
  • 19h - Get default drive - NO, only 1 disk
  • 1Ah - Set disk transfer address - NO, no direct disk control
  • 1Bh - Get allocation info for default drive - NO, no direct disk control
  • 1Ch - Get allocation info for specified drive - NO, no direct disk control
  • 1Fh - Get disk parameter block for default drive - NO, no direct disk control
  • 21h - Random read - YES, file read
  • 22h - Random write - YES, file write
  • 23h - Get file size in records - YES, file size
  • 24h - Set random record number - NO
  • 25h - Set interrupt vector - YES, per-device
  • 26h - Create PSP (Program Segment Prefix?) - NO
  • 27h - Random block read - NO
  • 28h - Random block write - NO
  • 29h - Parse filename - NO
  • 2Ah - Get date - NO, part of time get
  • 2Bh - Set date - NO, part of time set
  • 2Ch - Get time - YES, 64bit unix time
  • 2Dh - Set time - YES, 64bit unix time
  • 2Eh - Set verify flag (disk write verify) - YES, part of file open
  • 2Fh - Get disk transfer address - NO, no direct disk control
  • 30h - Get DOS version - YES
  • 31h - Terminate and stay resident - NO, no multitasking
  • 32h - Get disk parameter block for specified drive - NO, no direct disk control
  • 33h - Get or set Ctrl-Break - NO
  • 34h - Get InDOS flag pointer - NO
  • 35h - Get interrupt vector - NO, why be able to get ISRs?
  • 36h - Get free disk space - YES
  • 37h - Get or set switch character
  • 38h - Get or set country info - NO, no localization
  • 39h - Create subdirectory - YES
  • 3Ah - Remove subdirectory - NO, part of file delete
  • 3Bh - Change current directory - YES
  • 3Ch - Create or truncate file - NO, duplicate
  • 3Dh - Open file - NO, duplicate
  • 3Eh - Close file - NO, duplicate
  • 3Fh - Read file or device - NO, duplicate
  • 40h - Write file or device - NO, duplicate
  • 41h - Delete file - NO, duplicate
  • 42h - Move file pointer - YES, file seek
  • 43h - Get or set file attributes - NO, duplicate
  • 44h - I/O control for devices - NO, device-specific calls
  • 45h - Duplicate handle - NO, multitasking related?
  • 46h - Redirect handle - NO
  • 47h - Get current directory - YES
  • 48h - Allocate memory - YES, mem alloc
  • 49h - Release memory - YES, mem free
  • 4Ah - Reallocate memory - YES, mem realloc
  • 4Bh - Execute program - YES
  • 4Ch - Terminate with return code - NO, return from main()
  • 4Dh - Get program return code - NO
  • 4Eh - Find first file - NO, duplicate
  • 4Fh - Find next file - NO, duplicate
  • 50h - Set current PSP (Program Segment Prefix?) - NO
  • 51h - Get current PSP (Program Segment Prefix?) - NO
  • 52h - Get DOS internal pointers (SYSVARS) - NO
  • 53h - Create disk parameter block - NO, no direct disk control
  • 54h - Get verify flag - NO
  • 55h - Create program PSP (Program Segment Prefix?) - NO
  • 56h - Rename file - YES
  • 57h - Get or set file date and time - NO?
  • 58h - Get or set allocation strategy - NO
  • 59h - Get extended error info - NO
  • 5Ah - Create unique file - NO
  • 5Bh - Create new file - NO, duplicate
  • 5Ch - Lock or unlock file - NO, no multitasking
  • 5Dh - File sharing functions - NO
  • 5Eh - Network functions - NO, no networking
  • 5Fh - Network redirection functions - NO, no networking
  • 60h - Qualify filename - NO
  • 62h - Get current PSP (Program Segment Prefix?) - NO
  • 63h - Get DBCS lead byte table pointer - NO
  • 64h - Set wait for external event flag
  • 65h - Get extended country info - NO, no localization
  • 66h - Get or set code page - NO, no localization
  • 67h - Set handle count - NO
  • 68h - Commit file (flush file buffer?) - NO, no IO buffers
  • 69h - Get or set media ID - NO, no direct disk control
  • 6Ah - Commit file (flush file buffer?) - NO, duplicate
  • 6Ch - Extended open/create file - NO, duplicate
• 22h - Program terminate address - NO
• 23h - Control-C handler address - NO, no console
• 24h - Critical error handler address - YES?
• 25h - Absolute disk read - NO, no direct disk control
• 26h - Absolute disk write - NO, no direct disk control
• 27h - Terminate and stay resident - NO, no multitasking
• 28h - Idle callout - YES, sleep
• 29h - Fast console output - NO, no console
• 2Ah - Networking and critical section - NO, no networking
• 2Eh - Reload transient - NO
• 2Fh - Multiplex (interrupt multiplexer?) - NO

PlayStation Portable kernel API

From PPSSPP source code

• callback
  • example
    1. os_Status file_read_async(u32 id, size buffer_size, void (*handler)(os_Status status, void *buffer, size buffer_size))
       • allocates buffer
    2. void handler(os_Status status, void *buffer, size buffer_size)
       • handler caller sets buffer to buffer allocated in file_read_async()
  • pro
    • simple to implement
  • con
    • spaghetti code
      • C doesn't allow anonymous or nested function declaration
  • note
    • os_Status returned from file_read_async() is for reporting issues with the queue
    • os_Status as param of handler() is for reporting issue with the operation
• wait
  • example
    1. os_Status file_read_async(u32 id, size buffer_size, volatile u32 *out_ticket)
       • ticket is an ID unique to each operation requested
       • allocates buffer
    2. os_Status file_read_wait(u32 ticket, void **out_buffer, size *out_buffer_size)
       • sleeps program until operation completes
       • sets out_buffer to buffer allocated in file_read_async()
  • pro:
    • cleaner code
  • con:
    • program can't do anything else while waiting
      • need to delay calling wait as much as possible
    • not simplest

notes:

• "user" and "program" both mean the user program (ie not the kernel)
• stuff to consider
  • cleanliness of program code
  • handling 1 request
  • handling >1 request to the same resource
    • use a queue?
  • handling >1 request to different resources
    1. "load this data from SD"
    2. "use this data for gfx"
• for read, buffer should be allocated, written only once
  1. allocated, written by kernel
  2. user responsibility to free