Changes between Version 16 and Version 17 of Internal/OpenFlow/QuantaSetup

Timestamp:

Jun 14, 2011, 7:23:14 PM (13 years ago)

Author:

akoshibe

Comment:

—

Internal/OpenFlow/QuantaSetup

@@ -121 +121 @@
 
 == III A u-boot Primer == #III
-This section is a HOW-TO for using u-boot with respect to the Quanta, e.g. variables, scripts, and memory maps unique to this switch. !OpenFlow related u-boot stuff can be found in the [#IV next section].
+This section is a HOW-TO for scripting in u-boot with respect to the Quanta, e.g. variables, scripts, and memory maps unique to this switch. !OpenFlow related u-boot stuff can be found in the [#IV next section].
 
 === 3.1 Environment variables ===
@@ -152 +152 @@
 
 }}}
-Each entry is a line of the form [variable name]=[parameters]. the parameters can be a combination of u-boot commands and other variables in a way similar to a simple shell script.  
-
-The general case for these variables can be summarized as follows:
-
- * syntax is `[name]=[parameters]`, where [parameter] is some string
- * `$[name]` returns the value of the separately defined variable, [name]
+The output above is from a fresh Quanta out of the box. Each entry is a line of the form [variable name]=[parameters]. the parameters can be a combination of u-boot commands and other variables in a way similar to a simple shell script.  
+
+The general syntax for these variables can be summarized as follows:
+
+ * `[name]=[parameters]`, where [parameter] is some string relevant to the variable, [name]
+ * `$[name]` returns the value of a variable, [name], which is defined in a separate line (same as in bash shell scripting)
  * semicolon (;) delimits individual commands  
 
-For example, note the first two entries in the "screen shot" above:
+Variable definitions can be inlined as parameters for other variables. For example, note the first two entries in the "screen shot" above:
 {{{
 <entry 1> flash_bootcmd=setenv bootargs root=/dev/ram console=ttyS0,$baudrate; bootm ffd00000 ff000000 ffee0000
-<entry 2> cfcard_bootcmd=setenv bootargs root=/dev/ram console=ttyS0,$baudrate; ext2load ide 0:1 0x1000000 /uImage;ext2load ide 0:1 0x2000000/uInitrd2m;ext2load ide 0:1 0x400000 /LB9A.dtb;bootm 1000000 2000000 400000
-}}}   
-they were part of the `run` commands mentioned earlier. The parameters to these variables create another variable called "bootargs" using command `setenv`. What follows are the parameters for this new variable (which are also environment variables): 
+<entry 2> cfcard_bootcmd=setenv bootargs root=/dev/ram console=ttyS0,$baudrate; ext2load ide 0:1 0x1000000 /uImage;ext2load ide 0:1 0x2000000 /uInitrd2m;ext2load ide 0:1 0x400000 /LB9A.dtb;bootm 1000000 2000000 400000
+}}}    
+Both `flash_bootcmd` and `cfcard_bootcmd` are part of the `run` commands from the previous section that boot the different Linux images. These entries are made up of multiple strings comprised of u-boot commands and variable declarations and separated by semicolons. The first strings for both define a new variable called "bootargs" using command `setenv`. `setenv` is given multiple variables that define "bootargs": 
 
  * `root=/dev/ram` - probably specifies where the root filesystem should be loaded^2^
  * `console=ttyS0` - set output to /dev/ttyS0 
- * `$baudrate` - use the parameters specified in the variable "baudrate," which we can see above is set to 115200 (baud)
-
-The parameters that follow the semicolon after `$baudrate` differ a bit for the two variables. For the cfcard_bootcmd entry the `ext2load` commands specifies where to fetch the kernel, ramdisk, and device tree files from, respectively. The specific syntax for each `ext2load` command is: 
-
- `ext2load [interface] [memory address]`
-
-What is really important here are the memory location values. For the cf card, the values should be:
- * 0x1000000 for kernel image
- * 0x2000000 for filesystem
- * 0x400000 for the device tree 
+ * `$baudrate` - use the parameters specified in the variable "baudrate," which we can see is set to 115200 (baud) in the above `printenv` output
+
+The strings that follow the semicolon after `$baudrate` differ a bit for the two variables. For the cfcard_bootcmd entry the `ext2load` commands specifies where to fetch the kernel, ramdisk, and device tree files from, respectively. The specific syntax for each `ext2load` command is: 
+
+ `ext2load [interface] [memory address] [path to file]`
+
+What is really important here (and for troubleshooting things) are the memory location values. For the cf card, the values should be:
+ * 0x1000000 for kernel image (uImage)
+ * 0x2000000 for filesystem (uInitrd2m)
+ * 0x400000 for the device tree (LB9A.dtb)
 
 The same follows for the flash image, with ffd00000, ff00000, and ffee0000 being the address locations where the kernel, ramdisk, and device tree files always begin, respectively. The current version of u-boot has some tools for inspecting flash memory. These will be discussed in the [#ts troubleshooting section].      
 
-Both script variables end with the `bootm` command, which loads the program files from the memory locations given by `ext2load` in the cf card or implied in the flash.   
+Both variable definitions end with the `bootm` command, which loads the program files from the memory locations given by `ext2load` in the cf card or implied in the flash. `bootm` takes parameters as follows:
+ 
+ `bootm [kernel img. address] [filesystem address] [device tree address]`   
 
 === 3.2 modifying the environment variables list ===
-`setenv` allows you to modify and create environment variables. In general:
-
- * `setenv [name]`, where [name] is new, creates a new variable with that name. 
- * `setenv [name]`, where [name] already exists, wipes out its previous parameters. 
- * `setenv [name] [parameters]` sets/overwrites parameters for the variable [name] with [parameters].  
- 
-''Long parameters.'' For variables with whitespaces in its parameters (e.g. "script variables" like flash_bootcmd), the parameters have to be surrounded by single quotes to let u-boot know that everything is part of a single script. For example, to create and configure the variable dn_boot, we'd type this at the command line:
+`setenv` allows you to modify, create, and delete environment variables. In general:
+
+ * `setenv [name] [parameters]`, where [name] is new, creates a new variable called [name] defined by parameters specified in [parameters]. 
+ * `setenv [name]`, where [name] already exists, deletes the variable. 
+ * `setenv [name] [parameters]` where [name] already exists, overwrites old parameters for the variable [name] with [parameters].  
+ 
+''Long parameters.'' For variables with whitespaces in its parameters (e.g. "script variables" like flash_bootcmd), the parameters have to be surrounded by single quotes to let u-boot know that everything is part of a single script. For example, to create and configure the variable dn_boot (this script tells u-boot to fetch the filesystem via network using NFS and to boot from flash), we'd type this at the u-boot prompt:
 
 {{{
@@ -197 +199 @@
 }}}  
 
-Note the single quotes before `dhcp` and after `ffee0000`. Another important thing about long parameters is that they cannot contain newlines; The whole command must be typed in a single line.    
-
-=== 3.3 Some important variables ===
-
- * http://www.openflow.org/wk/index.php/IndigoConfiguration - !OpenFlow specific variables
+Note the single quotes before `dhcp` and after `ffee0000`. Another important thing about long parameters is that they cannot contain newlines or backslashes; The whole command must be typed as a single line.    
+
+=== 3.3 boot parameters ===
+Most long variables are bootup scripts. By default, there are two bootup scripts on a Quanta: `cfcard_bootcmd` and `flash_bootcmd`. As you can see throughout these docs, a user can easily create new bootup scripts of any arbitrary name. 
+
+A script called [name] can be run by invoking it with the `run` command. For example, to run `dn_boot`, you'd type
+ 
+ `run dn_boot` 
+
+at the u-boot prompt. This runs the command only once. In order to make a bootup script persist (e.g. be the default one that the switch boots to), you must set the variable `bootcmd` to the run command. The default script used in these switches is `cfcard_bootcmd`. You can see that in the `printenv` output.
+
+{{{
+=> printenv
+
+...
+
+bootcmd=run cfcard_bootcmd
+}}}
+
+=== 3.4 Flashing the switch/testing out images ===
+The `copy` command is the primary way to flash the switch with new firmware, as well as for updating u-boot itsself:
+
+ {{{
+copy <-b/-k/-r/-d> <tftp://serverip/filename | xmodem>
+        <-b/-boot> boot image file
+        <-k/-kernel> kernel image file
+        <-r/-ramdidk> ramdisk image file
+        <-d/-dtb> Device Tree Binary file
+ }}}
+
+`copy` leverages TFTP in order to fetch files into the proper locations in flash memory. Memory locations and file type are implied through flags; as such, `copy` does not check for consistency between flag and file type of the file you specify. This makes it critical that you double-check the flags and filenames you give `copy`^3^.
+
+Firmware updates may also be done via NFS. Usages of both `copy` and bootup via NFS are covered in [#IV section IV]. 
+
+Another tool to consider is the system shell, available from the CF card Linux image. For example, if you don't want to flash the new firmware, one can just add the images to /cf_card and point a u-boot script to the names of the new files:
+
+{{{
+cfboot=setenv bootargs root=/dev/ram console=ttyS0,$baudrate; ext2load ide 0:1 0x1000000 /uImage2;ext2load ide 0:1 0x2000000 /uInitrd2m2;ext2load ide 0:1 0x400000 /LB9A2.dtb;bootm 1000000 2000000 400000
+}}}
+
+`cfboot` can then be manually started with the command `run cfboot`, or be set as the default boot parameter by setting it as `bootcmd`'s parameter.  
  
 === 3.4 troubleshooting === #ts
-
+Mis-configurations in u-boot can cause various interesting^4^ issues including non-persistent configurations, hanging on bootup, and bricked switches. The first two are mildly annoying; the latter requires a JTAG cable and is serious enough an issue that everyone is discouraged from touching u-boot unless absolutely necessary. A Grid service is provided for manipulating the Quantas.  
+
+=== 3.4.1 Flash memory ===
+U-boot comes with tools such as `imls` and `flinfo` that allow you to inspect flash memory. Under normal circumstances, the memory map of the switch should look like below. Note the memory location and size of the ramdisk and kernel images. Any deviation can be a potential issue e.g the use of wrong firmware and wrongly copied files.  
+
+{{{
+=> imls
+Image at FF000000:
+   Image Name:   
+   Image Type:   PowerPC Linux RAMDisk Image (gzip compressed)
+   Data Size:    12275941 Bytes = 11.7 MB
+   Load Address: 00000000
+   Entry Point:  00000000
+   Verifying Checksum ... OK
+Image at FFD00000:
+   Image Name:   Linux-2.6.27
+   Image Type:   PowerPC Linux Kernel Image (gzip compressed)
+   Data Size:    1742743 Bytes =  1.7 MB
+   Load Address: 00000000
+   Entry Point:  00000000
+   Verifying Checksum ... OK
+}}}
+
+A more detailed memory map can be found with flinfo. The 'E' next to the octets indicate empty spots in memory, RO write protected spots. 
+
+{{{
+=> flinfo
+
+Bank # 1: CFI conformant FLASH (16 x 16)  Size: 32 MB in 256 Sectors
+  AMD Standard command set, Manufacturer ID: 0x01, Device ID: 0x7E2201
+  Erase timeout: 4096 ms, write timeout: 1 ms
+  Buffer write timeout: 3 ms, buffer size: 64 bytes
+
+  Sector Start Addresses:
+  FE000000        FE020000        FE040000        FE060000 E      FE080000 E    
+  FE0A0000 E      FE0C0000 E      FE0E0000 E      FE100000 E      FE120000 E    
+  FE140000 E      FE160000 E      FE180000 E      FE1A0000 E      FE1C0000 E    
+  FE1E0000 E      FE200000 E      FE220000 E      FE240000 E      FE260000 E    
+  FE280000 E      FE2A0000 E      FE2C0000 E      FE2E0000 E      FE300000 E    
+
+...
+
+  FFE00000        FFE20000        FFE40000        FFE60000        FFE80000      
+  FFEA0000        FFEC0000 E      FFEE0000        FFF00000   RO   FFF20000   RO 
+  FFF40000 E      FFF60000 E      FFF80000 E      FFFA0000 E      FFFC0000   RO 
+  FFFE0000      
+
+}}}
+
+The output can be pretty big. It is also far less intuitive than `imls` (and often less useful). 
+
+=== 3.4.2 CF Card ===
+There are no means of inspecting the CF card from U-boot directly, maybe except from getting a glance of the memory map during (attempted) bootup. It should look like the following:
+
+{{{
+## Booting image at 01000000 ...
+   Image Name:   Linux-2.6.27-svn3877
+   Image Type:   PowerPC Linux Kernel Image (gzip compressed)
+   Data Size:    1711826 Bytes =  1.6 MB
+   Load Address: 00000000
+   Entry Point:  00000000
+   Verifying Checksum ... OK
+   Uncompressing Kernel Image ... OK
+## Loading RAMDisk Image at 02000000 ...
+   Image Name:   svn3877
+   Image Type:   PowerPC Linux RAMDisk Image (gzip compressed)
+   Data Size:    20822821 Bytes = 19.9 MB
+   Load Address: 00000000
+   Entry Point:  00000000
+   Verifying Checksum ... OK
+   Booting using the fdt at 0x400000
+   Loading Ramdisk to 1eae1000, end 1febcb25 ... OK
+}}}
+
+If the switch can boot from the CF Card, choosing the system shell will give you access to a shell that will let you poke around the CF card. It should be mounted as the /cf_card directory. 
+  
 == IV OpenFlow Switching == #IV
 This section provides example uses of the u-Boot facilities for manipulating the !OpenFlow properties of the LB9A. We will also introduce the ORBIT Grid Service facilities that can be used to configure the switch without dealing with the gory details of u-boot (given the switch has the proper firmware, that is).
@@ -361 +474 @@
 The ORBIT grid services allow you to query and configure various components of the testbed(s) through a browser from gw.orbit-lab.org. Here our focus is on the network services.
 
-==== !addOpenFlow ====
+==== addOpenFlow ====
 This allows you to set u-Boot environment variables without going into the gory details of u-Boot. For example, to boot a switch into !OpenFlow mode, issue the following command at the navigation bar on your browser from external2 (make sure you have X11 tunneling):
 {{{
@@ -380 +493 @@
 ^1. I honestly don't know what it does.^ [[BR]]
 ^2. These are educated guesses through observation, and by no means guaranteed to be what is actually happening. If anyone has an actual explanation I'd be very happy to learn about it.^
- 
+^3. The importance was demonstrated by a mix-up between the -b and -d flags for `copy`, which happily overwrote u-boot with the device tree, bricking the switch.^
+^4. There are no sarcasm tags in Wiki notation.^