Forth Lesson 13: Difference between revisions

From OLPC
Jump to navigation Jump to search
(added info about microEMACS)
 
(5 intermediate revisions by 3 users not shown)
Line 10: Line 10:
* Boot images can be explicitly loaded from either local storage devices or the network (TFTP, NFS, HTTP)
* Boot images can be explicitly loaded from either local storage devices or the network (TFTP, NFS, HTTP)


=== Overview ===
== Overview ==


In this lesson we'll cover how to write Forth programs and save them
In this lesson we'll cover how to write Forth programs and save them
in persistent storage on the XO.
in persistent storage on the XO, by introducing commands that deal with files.


=== Storage options ===
== Storage options ==


The OFW and EC code both reside in SPI FLASH. There is extra room there
The OFW and EC code both reside in SPI FLASH. There is extra room there
Line 30: Line 30:


OFW can write to files on FAT-16 and FAT-32 filesystems, so you can
OFW can write to files on FAT-16 and FAT-32 filesystems, so you can
use USB keys and SD memory cards to store your own files. An SD memory
use USB keys and SD memory cards to store your own files.
card is a good choice for adding personal storage, so the examples
will use filenames on the SD memory filesystem.


Files are specified with a device, optional partition number, optional directories, a name, and a type.
=== Text editing ===


device:partition,\directory\subdirectory\file.type
As of release Q2E15, OFW contains a microEMACS text editor. To run it, type

Examples of filesystem devices are:
*a USB drive {{Code|u:}}
*an SD card in the external slot {{Code|ext:}}
*the internal storage {{Code|int:}}
*the Open Firmware dropin collection {{Code|rom:}}
*an NFS server {{Code|nfs:}}
*a web server {{Code|http:}}
*an FTP server {{Code|ftp:}}

Note the use of {{Code|\}} instead of {{Code|/}}. This is because {{Code|/}} is part of the device specification.

== Commands ==

=== List Directory ===

ok dir u:\

=== See a file ===

ok more u:\my.txt

ok more u:\boot\olpc.fth

=== Copy a file ===

ok copy u:\my.txt u:\yours.txt

=== Delete a file ===

ok del u:\file.txt

=== Rename a file ===

ok rename u:\fiance.txt u:\wife.txt

=== Make a directory ===

ok mkdir u:\attic

=== Remove a directory ===

ok rmdir u:\attic

=== Redirect output to a file ===

ok to-file u:\words.txt words

(to recover from a hang during ''to-file'', press interrupt key, nothing will seem to happen; then type ''unsave-output'' to get the ok prompt back, and ''ofd @ fclose'' to close the file. See also <trac>12877</trac>.)

=== Estimate free space on filesystem ===

ok disk-free u:\

== Text editor ==

Open Firmware contains the microEMACS text editor. To run it, type


ok emacs
ok emacs
Line 47: Line 102:


When you specify filenames to microEMACS, you have to use the OFW syntax, because microEMACS relies of OFW for all of its I/O and system functions. microEMACS can only write to filesystems that OFW knows how to write, so while you can use it to view files on NAND FLASH, you can't write changes back to NAND FLASH. You could, however, open a file from NAND, edit it, and write it back to a USB key.
When you specify filenames to microEMACS, you have to use the OFW syntax, because microEMACS relies of OFW for all of its I/O and system functions. microEMACS can only write to filesystems that OFW knows how to write, so while you can use it to view files on NAND FLASH, you can't write changes back to NAND FLASH. You could, however, open a file from NAND, edit it, and write it back to a USB key.

== Editing via wireless ==


If you have an open wireless access point, try this:
If you have an open wireless access point, try this:
Line 53: Line 110:
ok emacs http:\\dev.laptop.org\pub\firmware\scripts\batman.fth
ok emacs http:\\dev.laptop.org\pub\firmware\scripts\batman.fth


== Editing in memory ==
The information below is mostly of historical interest if you have a recent OFW with microEMACS.

The information below is mostly of historical interest, or if you have no filesystems.


OFW has a simple editor; it is the same one that is used for editing
OFW has a simple editor; it is the same one that is used for editing
Line 62: Line 121:
^C
^C
Store script to NVRAM [y/n]? y
Store script to NVRAM [y/n]? y
ok
ok


It doesn't really store the data to NVRAM, because the OLPC machine
It doesn't really store the data to NVRAM, because the OLPC machine
Line 76: Line 135:
<executes the contents of nvramrc as Forth code>
<executes the contents of nvramrc as Forth code>
ok nvramrc eval \ Same as above but shorter
ok nvramrc eval \ Same as above but shorter
ok
ok

=== Saving and loading ===


To save it to disk, you could write this definition:
To save it to disk, you could write this definition:
Line 121: Line 178:
maxlen -- newlen )" . If you want to do your own buffer management, you
maxlen -- newlen )" . If you want to do your own buffer management, you
could use that to build a custom set of editing words.
could use that to build a custom set of editing words.

''Thus endeth the lesson.''


'''[[Forth Lesson 14|Next Lesson: Some Cute Hacks]]'''
'''[[Forth Lesson 14|Next Lesson: Some Cute Hacks]]'''

Latest revision as of 00:56, 2 April 2015

Mitch Bradley's Forth and
Open Firmware Lessons:

See also the first section of this page for editing files on an external device like a USB stick or SD card.

Review

In the previous lesson we learned that:

  • Console I/O operates directly on a framebuffer (text is rendered by Forth code)
  • OFW can boot from ELF images, Linux bzImage files, or Forth source files
  • Boot images can be explicitly loaded from either local storage devices or the network (TFTP, NFS, HTTP)

Overview

In this lesson we'll cover how to write Forth programs and save them in persistent storage on the XO, by introducing commands that deal with files.

Storage options

The OFW and EC code both reside in SPI FLASH. There is extra room there that, in principle, could be used to store user-entered stuff, but there are some practical problems. There is the risk of bricking the machine, from which recovery is possible, but extremely tedious, requiring a special dongle and an on-board connector that is often unpopulated. There is also the problem that, in order to write to the SPI FLASH, it is necessary to hold the EC's 8051 in reset (so it doesn't interfere with the programming by doing microcode instruction fetches from the same serial bus that the programming commands go over). While the 8051 is in reset, the keyboard doesn't work, and when you have finished programming, you have to restart the 8051, which resets the whole system.

OFW can write to files on FAT-16 and FAT-32 filesystems, so you can use USB keys and SD memory cards to store your own files.

Files are specified with a device, optional partition number, optional directories, a name, and a type.

device:partition,\directory\subdirectory\file.type

Examples of filesystem devices are:

  • a USB drive u:
  • an SD card in the external slot ext:
  • the internal storage int:
  • the Open Firmware dropin collection rom:
  • an NFS server nfs:
  • a web server http:
  • an FTP server ftp:

Note the use of \ instead of /. This is because / is part of the device specification.

Commands

List Directory

  ok dir u:\

See a file

  ok more u:\my.txt
  ok more u:\boot\olpc.fth

Copy a file

  ok copy u:\my.txt u:\yours.txt

Delete a file

  ok del u:\file.txt

Rename a file

  ok rename u:\fiance.txt u:\wife.txt

Make a directory

  ok mkdir u:\attic

Remove a directory

  ok rmdir u:\attic

Redirect output to a file

  ok to-file u:\words.txt  words

(to recover from a hang during to-file, press interrupt key, nothing will seem to happen; then type unsave-output to get the ok prompt back, and ofd @ fclose to close the file. See also <trac>12877</trac>.)

Estimate free space on filesystem

  ok disk-free u:\

Text editor

Open Firmware contains the microEMACS text editor. To run it, type

  ok emacs

You can also specify the name of a file on the command line, for example:

  ok emacs u:\boot\olpc.fth

microEMACS has built-in help; just look at the red window to get started. You can get more help by typing the F1 key then scrolling the pop-up help window. You can do simple editing by typing and using the arrow keys to move around. For more complex tasks you can use many of the common ctrl and esc commands that are present in full EMACS. (The one feature I really miss from full EMACS is filename completion.)

When you specify filenames to microEMACS, you have to use the OFW syntax, because microEMACS relies of OFW for all of its I/O and system functions. microEMACS can only write to filesystems that OFW knows how to write, so while you can use it to view files on NAND FLASH, you can't write changes back to NAND FLASH. You could, however, open a file from NAND, edit it, and write it back to a USB key.

Editing via wireless

If you have an open wireless access point, try this:

  ok wifi <your_essid>
  ok emacs http:\\dev.laptop.org\pub\firmware\scripts\batman.fth

Editing in memory

The information below is mostly of historical interest, or if you have no filesystems.

OFW has a simple editor; it is the same one that is used for editing command lines, but it also works for multi-line memory buffers.

  ok nvedit
  <Edit using arrow keys or basic emacs>
  ^C
  Store script to NVRAM [y/n]? y
  ok █

It doesn't really store the data to NVRAM, because the OLPC machine doesn't have any (CMOS RAM is too small, and SPI FLASH has the problems listed above). What it does is save the data in memory, where you can get it back with "nvramrc ( -- adr len )".

  ok  nvramrc .s
  ff9f4baa 3d
  ok nvramrc list
  <whatever you put in there>
  ok nvramrc evaluate
  <executes the contents of nvramrc as Forth code>
  ok nvramrc eval              \ Same as above but shorter
  ok █

To save it to disk, you could write this definition:

  : nvwrite  \ filename  ( -- )
    safe-parse-word  $create-file >r    nvramrc " write" r@ $call-method
  drop  r> close-dev
  ;

then

  ok nvwrite sd:\myfile.fth

then one of these lines to evaluate the Forth code from disk:

  ok including sd:\myfile.fth       \ For standards-aware persons
  ok fload sd:\myfile.fth           \ Another way to say the same thing
  ok fl sd:\myfile.fth              \ For impatient people like me

$create-file will not overwrite an existing file. You can delete it with:

  ok  rm sd:\myfile.fth

Or you could modify nvwrite as follows:

  : nvwrite  \ filename  ( -- )
    safe-parse-word  2dup ?delete-file  if
      $create-file >r    nvramrc " write" r@ $call-method drop  r> close-dev
    then
  ;

Here is a definition that will read a file into nvramrc so you can edit it

  : nvread  \ filename  ( -- )
    reading
    load-base   dup h# 10000  ifd @ fgets   ( adr len )
    to nvramrc
    ifd @ fclose
  ;

The primitive editing routine that nvedit uses is "edit-file ( adr len maxlen -- newlen )" . If you want to do your own buffer management, you could use that to build a custom set of editing words.

Thus endeth the lesson.

Next Lesson: Some Cute Hacks