Forth Lesson 23

Random Recipes

This is a collection of "How to Do X" snippets. Feel free to add your favorites.

Changing the prompt

ok : si ." si " ;
ok ' si to (ok)
si 

Undo with

si ' "ok" is (ok)
ok █

Adding status data to the prompt

ok : .voltage  uvolt@ .milli ." V "  ;
ok ' .voltage to status
6.74V ok █

XO-1.75 Heavy Load

This is a trick for running several XO-1.75 subsystems simultaneously, thus forcing a high power draw. The subsystems are audio, camera, and wireless LAN transmit.

 ok dev /camera
 ok patch false shoot-still selftest
 ok patch exit ?dup selftest
 ok dend
 ok test /camera
 ok select /audio
 ok patch 20 -9 tone
 ok patch abort install-playback-alarm start-audio-out
 ok d# 100 tone
 ok dend
 ok nb-tx: u:\os6.zd

It depends on the fact that both the camera and the audio use DMA to do most of the work, and they can run autonomously.

Forcing EC Code Update on XO-1.75 and XO-4

On XO-1.75 and XO-4, the Embedded Controller code is executed from FLASH internal to the EC (on previous XOs, the EC code was executed from the same SPI FLASH chip that contained the Open Firmware code). The OFW SPI FLASH contains a copy of the EC code, and if that copy is newer than the running EC code, OFW auto-updates the EC code by writing the new copy into the internal EC FLASH.

There are circumstances where the auto-update doesn't work the way you want it; for example you might have a test version that doesn't register as "newer" than the running version. Or you might want to force a reversion to an older version.

To explicitly perform the EC FLASH update:

  ok flash-ec rom:ecimage.bin

For safety, that command requires the presence of both battery and AC power. You can bypass that safety check with:

  ok flash-ec! rom:ecimage.bin

rom:ecimage.bin refers to the copy of the EC code that is stored inside the OFW SPI FLASH. More generally, "rom:" refers to a "filesystem" inside that SPI FLASH, containing numerous images that OFW needs from time to time.

The target of the flash-ec command can be any file that OFW can access. For example:

  ok flash-ec u:mynewec.bin                         \ From USB stick
  ok flash-ec http:\\192.168.200.200\ecimage3.bin   \ From the web

Wireless Network Access from Open Firmware

OFW contains a network stack that supports numerous protocols including HTTP, Telnet, SMB (Windows File Sharing), TFTP, and NFS. On the XO, the network connection can be either the built-in wireless LAN or a plug-in USB Ethernet adapter. If a plug-in Ethernet adapter is present, it is used as the default network device, otherwise the wireless LAN is used.

Connecting to the Wireless LAN

You can list the wireless access points within range with:

  ok test /wlan
  RSSI: 49 SSID: OLPCOFW  Channel: 1
  RSSI: 49 SSID: 5247 1201  Channel: 1
  RSSI: 85 SSID: 09FX07016302  Channel: 6

By default, when you try to use the wireless LAN, OFW-on-XO tries to associate with an open access point named "OLPCOFW". If you want to perform wireless operations on a lot of XOs, you can set up such an access point to streamline subsequent operations.

You can manually change the association by specifying the ESSID of a different access point with:

  ok essid 09FX07016302

If your access point requires authentication, you must supply the password after establishing the essid. The command for setting the password depends on the type of security.

For the older "WEP" security:

  ok wep 00224488aa                   \ 40-bit/5-byte hex key format
  ok wep 00112233445566778899aabbcc   \ 128-bit/13-byte hex format
  ok " MyPwd" $wep                    \ 5-byte ASCII format
  ok " MyPassword123" $wep            \ 13-byte ASCII format

For the newer "WPA" and "WPA2" security:

  ok wpa MyPassword

After you have entered the ESSID and optionally the authentication information, OFW network commands will automatically associate with the access point as needed. You can also add these to a laptop using the NN and PP tags.

Setting Clock

You can use NTP to set the clock:

  ok essid mine
  ok ntp-set-clock

This searches for an NTP server by trying, in order:

• the NTP server identified by the DHCP server,
• the host name "time",
• the address 172.18.0.1,
• several host names in the "pool.ntp.org" collection.

The search can take a little while if the DHCP server has no NTP server configured. You can speed it up if you have an NTP server by typing in the address in a special command:

  ok : x  " 10.0.0.18"  ;  ' x to ntp-servers
  ok ntp-set-clock

Connecting to any Wireless LAN

Sometimes it might not be possible to know the ESSID in advance, yet you know it starts with a certain word. This happens in schools. The following code fragment can be used where the only access points that match the prefix school are those that can be used.

: prefix$  " school"  ;

d# 34 buffer: an-ssid
: an-ssid0  ( -- )        0 an-ssid c!  ;
: an-ssid!  ( ssid$ -- )  d# 32 min  an-ssid pack drop  ;
: an-ssid@  ( -- ssid$ )  an-ssid count  ;

dev /supplicant
: capture-ssid  ( ssid$ -- )
   \ test for hidden access point, first byte of essid is zero
   over c@  if          ( ssid$ )
      2dup
      prefix$           ( ssid$ ssid$ prefix$ )
      rot drop comp     ( ssid$ comparison )
      0= if
         \ a match by prefix, capture the ssid for re-use
         2dup an-ssid!
      then
   then                 ( ssid$ )
   type                 ( )
;
patch capture-ssid type .ie-short
dend

scan-wifi an-ssid@ $essid

The code works by intercepting the scan results, testing each name, and when it matches storing the name for later use. Then the latest stored name is used.

Some OFW Network Commands

The following network commands work on both wireless and wired (via a USB Ethernet adapter) networks.

  ok ping 192.168.200.1
  Scan for: OLPCOFW found
  Associate with: OLPCOFW
  DHCP got 192.168.200.22
  4 ms

If your DHCP server reports the name server address, OFW can use it to resolve hostnames:

  ok ping dev.laptop.org
  Associate with: OLPCOFW
  112 ms

If ping hangs, and does not respond to any key, use the keyboard interrupt.

The "Scan for:" and "DHCP got" messages are only shown once; OFW caches the information after the first time, so subsequent operations are faster.

  ok more http:\\firmworks.com\index.htm
  (displays some HTML as ASCII)

The more command is not network-specific; it will display any file. This illustrates the fact that any OFW file-oriented command can apply to a network file by using the "http:\\SERVER\FILE" syntax. Note the use of backslashes (\) instead of forward slashes (/). This is an unfortunate consequence of OFWs use of forward slash to separate pathname components in the device tree.

  ok fload smb:\\USER:PASSWORD@SERVER\path\to\file.fth

The above shows an example of loading a Forth source code file from a Windows share (SMB server). You can also say "cifs" instead of "smb" - CIFS (Common Internet File System) and SMB (Server Message Block) are different names for the same thing.

OFW speaks NFS (Network File System) too:

  ok fload nfs:\\SERVER\path\to\file.fth

You can use TELNET to talk to OFW from another machine, or vice versa, see Firmware/Remote.

You can update OFW via the network:

  ok flash http:\\dev.laptop.org\pub\firmware\q4b09\q4b09.rom
  Reading http:\\dev.laptop.org\pub\firmware\q4b09\q4b09.rom
  Scan for: OLPCOFW found
  Associate with: OLPCOFW
  DHCP got 192.168.200.22
  Got firmware version: CL2   Q4B09  Q4B
  Checking integrity ...
  (etc)

Keeping the WLAN active

select ip

or

d# 1000 to #pings   ping 10.0.0.1

which pings an IP address 10.0.0.1 for 1000 cycles.

Ping server

pingd

Listens for ICMP echo request packets and sends an echo reply. Press a key to stop.

Uses the destination IP address in the echo request for forming the echo reply. When a Linux peer is using "ping -b", the replies are not printed, because the source IP of the arriving packets is the broadcast address. To fix this, prepend this fragment:

\ respond to broadcast packets with our own ip address
: exchange-ips'
   'ip-src  'ip-dst  4  exchange-bytes
   " my-ip-addr" $call-net 'ip-src 4 move
;
patch exchange-ips' exchange-ips echo-packet

Checking DHCP

1 to bootnet-debug
ping 10.0.0.1

Displays data about negotiation.

Without a DHCP server

If a wireless access point does not provide a DHCP server, or if you wish to avoid using one, Open Firmware can be configured manually for an IP address. Exactly which address to use is up to you. Here's an example:

setenv ip-address 10.0.0.250
setenv ip-dns-server 8.8.8.8
setenv ip-netmask 255.255.255.0
setenv ip-router 10.0.0.84
setenv ip-domain mit.edu
essid AP
telnetd
Scan for: AP found
Associate with: AP
telnet://10.0.0.250

sendmail

With a cooperative mail server, and preconfigured network, mail can be sent via SMTP, for example:

ok setenv smtp-server 10.0.0.1
ok setenv smtp-from-path user@host
ok setenv smtp-to-path user@host
ok setenv smtp-my-hostname host
ok " test message"r"n" sendmail
ok no-page collect( .dropins )collect sendmail

tcpdump

tcpdump and Wireshark compatible packet tracing support is available, and is very handy for network debugging of all kinds, for example:

ok capture u:\trace.cap   \ start a packet capture to a file on USB drive
ok [... some network action ...]
ok .capture               \ show capture status
ok stop-capture           \ stop the capture

The default packet capture length is 64 bytes. To increase to maximum, do this before capture:

ok dev /obp-tftp d# 1500 to capture-length dend

In Open Firmware prior to svn 3639 stop-capture is available in dev /obp-tftp.

md5sum of a small file

(the file must fit in memory)

: .md5 ( md5$ -- )
  push-hex
  bounds  ?do
     i c@  <# u# u# u#> type
  loop
  pop-base
;

: $md5sum-file  ( prefix$ filename$ -- )
  2dup $read-file abort" Read error" ( prefix$ filename$ adr len )
  2dup $md5digest1        ( prefix$ filename$ adr len md5$ )
  2swap free-mem          ( prefix$ filename$ md5$ )
  .md5                    ( prefix$ filename$ )
  ."  "                   ( prefix$ filename$ )
  2swap type              ( filename$ )
  type                    ( )
  cr
;

: md5sum  ( "file" -- )
  "  " safe-parse-word $md5sum-file
;

md5sum of a large file

XO-1.75 only.

Read a large file and calculate an MD5 checksum. The result should match the checksum displayed by the Linux md5sum command. Useful as a test of file content, and filesystem and device read performance. Is slower than the Linux equivalent, but by using the Open Firmware USB driver excludes Linux from a test.

: .md5 ( md5$ -- )
  push-hex
  bounds  ?do
     i c@  <# u# u# u#> type
  loop
  pop-base
;

h# 100000 value /buf
0 value ih
: md5sum-large ( "file" -- )
  safe-parse-word
  $open-canonical-file to ih
  use-md5 hash-init
  /buf alloc-mem >r
  " size" ih $call-method drop         ( input-file-size )
  begin  ?dup  while                   ( #remaining )
     r@  /buf " read" ih $call-method  ( #remaining #read )
     ?dup  0=  if
        r> /buf free-mem true abort" short read"
     then
     tuck -  r@ rot                    ( #remaining' adr #read )
     hash-update                       ( #remaining )
     [char] . emit
  repeat
  cr
  r> /buf free-mem
  ih close-dev
  hash-final                           ( digest$ )
  .md5 cr
;

Example usage:

ok t-hms( md5sum-large u:\os29.zd4 )t-hms
....
00:03:04

read a large file

Read a large file and ignore it. Useful as a test of filesystem and device read performance.

h# 100000 value /buf
0 value ih
: read-a-whole-file ( "file" -- )
  safe-parse-word
  $open-canonical-file to ih
  /buf alloc-mem >r
  " size" ih $call-method drop         ( input-file-size )
  begin  ?dup  while                   ( #remaining )
     r@  /buf " read" ih $call-method  ( #remaining #read )
     -                                 ( #remaining' )
     [char] . emit
  repeat
  cr
  r> /buf free-mem
  ih close-dev
;

Example usage:

ok t-hms( read-a-whole-file u:\fs.zd )t-hms
....
00:01:26

read a .zd file

Read a .zd file without inflating or writing to internal storage. Gives the time spent reading the file. Useful for estimating the cost of inflation and internal storage writes during an fs-update.

: zblocks:  get-hex# get-hex# 2drop  ;
: zblocks-end:  ;
: data:  safe-parse-word 2drop  ;
: zblock:
  get-hex# drop  get-hex#   ( comprlen )
  safe-parse-word 2drop  safe-parse-word 2drop     ( comprlen )
  1+  >r  load-base r@ source-id fgets r> <> abort" short read"
;
: fs-scan ( "file" -- )
  safe-parse-word r/o open-file abort" can't open"  ( fd )
  linefeed over force-line-delimiter  ( fd )
  t-hms(  ['] include-file catch  )t-hms  throw
;

Example usage:

ok fs-scan u:\fs.zd
00:01:45
ok █

(Total fs-update time was 5:05, time with null-fsdisk was 4:36, time with fs-scan was 01:45, therefore 2:51 is due to inflation of the compressed data.)

erase a device

Write all over a USB drive, erasing what is there.

d# 512 constant /block
d# 512 buffer: block
block /block ff fill
0 value ih
" u:0" open-dev to ih
: wa
   " size" ih $call-method /block um/mod nip
   dup .d cr 0 do
      i .d (cr
      block /block " write" ih $call-method drop
   loop
   cr
;
wa
ih close-dev

See also How to quickly erase everything for microSD, SD cards, and eMMC storage.

using an apple superdrive

The Apple USB SuperDrive requires a vendor-specific SCSI command before it will accept a disk into the mechanism. This prevents use in automatic booting of Open Firmware, unless we fix it. In the meanwhile, manual use can be achieved like this:

ok p2
USB devices:
/usb@d4208000/hub@0,0
/usb@d4208000/hub@0,0/scsi@2,0
/usb@d4208000/hub@0,0/scsi@2,0/disk
ok select /usb@d4208000/hub@0,0/scsi@2,0
ok show-children
  Unit 0   Removable Read Only device    Apple   SuperDrive      2.00
ok create mbasd-cmd  h# ea c, 0 c, 0 c,  0 c, 0 c, 0 c,  1 c,
ok 0 0 -1 mbasd-cmd h# 7 -1 retry-command? . .
0 0 
ok show-children                                             
  Unit 0   Removable Read Only device    HL-DT-STDVDRW  GX40N    RQ00
ok unselect
ok dir u:\

In Linux the command required is:

sudo yum install sg3_utils
sudo sg_raw /dev/sr0 ea 00 00 00 00 00 01

References:

• http://www.niftytechblog.com/2013/01/15/apple-usb-superdrive-a-cautionary-tale/
• https://bugzilla.redhat.com/show_bug.cgi?id=713509

Next Lesson: Device Tree Hacking