Assorted StyxMon docs Some features of the new StyxMon (vs the old one): - up to 6x faster transfer rates (56K, 76.8K, 115.2K, 230.4K) - no longer dependent on sboot - can execute both AIF and Plan9 binaries - can boot by just copying a file to /n/rdbg/boot - can read/write /n/rdbg/mem to get access to all of memory (new mdb utility aids with this) To initiate a connection to a StyxMon-enabled board: % echo b9600 > /dev/eia0ctl % imount /dev/eia0 /n/rdbg To connect at a faster rate: first connect at 9600: % echo b9600 > /dev/eia0ctl % imount /dev/eia0 /n/rdbg tell StyxMon what rate to use next time: % echo b38400 > /n/rdbg/ctl % unmount /n/rdbg now reconnect at the faster rate: % echo b38400 > /dev/eia0ctl % imount /dev/eia0 /n/rdbg To see the initial StyxMon startup message (including memory size, CPU speed, FID's opened, etc) after mounting: % cat /n/rdbg/ctl Note: the script /usr/ddk/lib/mashinit has menus to automatically handle connecting, changing the speed, downloading kernels, etc ----------------------------------------------------------------------------- StyxMon exported files: Initially, styxmon will export 4 files into the namespace, as 'ls /n/rdbg' shows: /n/rdbg/boot /n/rdbg/cons /n/rdbg/ctl /n/rdbg/mem Programs that are run from styxmon, such as sboot, can add additional files to the namespace that is exported. boot any file copied here will be executed, if it has a standard plan9 or AIF header. For example, to boot sbsword.aif (the AIF executable for sboot), do the following: % cp sbsword.aif /n/rdbg/boot This is equivalent to finding a region of memory that is known to be unused, and doing the following set of commands (assuming that such a region exists at 0x10000): % dd -if sbsword.aif -of /n/rdbg/mem -bs 1024 -oseek 64 % echo e0x10000 > /n/rdbg/ctl cons This is the console file, which can be read to get console output, and can be written to for 'typing' to the console for any program currently running on the device. For instance, to keep an ongoing log of console output: % cat /n/rbdg/cons& If sboot is running, a "P" command can be typed to it with: % echo P > /n/rdbg/cons For an interactive console: % cat /n/rbdg/cons& % cat >/n/rbdg/cons ctl This is the control file, to which the following commands can be written: E execute at the specified flash offset (ofs can be decimal, or hexadecimal with a 0x prefix) For instance, to execute the program at offset 0x8000 in the flash: % echo E0x8000 > /n/rdbg/ctl The program at the specified offset is expected to have a standard plan9 or AIF header. The address of the BPI (BootParam Interface) is passed as the first argument to the call to the entry routine. E execute the default boot program from flash e execute at the specified memory address S start at the specified flash offset. A call will actually be made directly to the specified address. The address of the BPI structure is still passed as the first argument. s start at the specified memory address r0 soft reset (reinitialize) r1 hard reset r reset to specified address. This allows alternate monitor code to be tested. Essentially, this stores a magic number and the address in registers that survive the reset, and when the system resets and sees the magic number, it vectors to the specified address instead of running the normal monitor initialization. x force the current program to exit with the specified exit code. This will return StyxMon to the "hangout" state. b set the serial speed to the specified value. This does not actually change the current speed, but instead changes the speed the board will connect at after it is unmounted. C console reset. This makes all text in the circular message buffer act as if it's new, so that the next read of cons or ctl will display all of it. For instance, if text was put in the circular message buffer and then the kernel crashed, the following can be done to recover the final messages: % echo C > /n/rdbg/ctl % cat /n/rdbg/ctl Or alternatively: % cat /n/rdbg/cons& % echo C > /n/rdbg/ctl ctl can also be read, in which case it acts like a non-blocking form of cons (i.e. -- it will just return the newest console output, then return EOF). In most cases, it is recommended to just leave a 'cat /n/rdbg/cons&' running instead, so that all console output can be seen when it becomes available. However, there may be cases where it is desireable just to capture new output at specified moments. Reading ctl makes this possible. mem mem is a seekable file that represents all of the device's memory. It should be used with utilities that selectively seek and read/write parts of it, such as dd and mdb. mdb is a utility designed for use with devices like mem. It could be used as follows to dump some SA1100 registers: % mdb /n/rdbg/mem 0xa0000000,10/X ----------------------------------------------------------------------------- mdb docs: mdb is a memory debugger that uses db or adb-style syntax. It is invoked with: % mdb [] If it is given a command, it will immediately execute that and return. Otherwise, it goes into an interactive console mode, taking adb-style commands for examining and changing memory, and returning the results. A manpage on db or adb should be sufficient to describe the commands, although mdb is a subset, so it only supports commands that directly deal with viewing or changing memory. The following format modifiers are supported: b, c, C x, d, u, o X, D, U, O, s, S, r, R, a, A, n, +, -, ^ w, W The following arithmetic operators and values are supported: ., +, ^, ", (, +, -, *, %, &, | ----------------------------------------------------------------------------- Misc notes: - in the StyxMon console output, a '*' on a line by itself means that StyxMon has returned to "hangout" mode, where it is just polling for styx messages, and nothing else is running. - StyxMon on the SA1100 uses DMA channel 3 to collect data from the FIFO's of serial port 3. If that serial port is to be reused for some other purpose, it is important to make sure that the DMA channel is disabled first. ----------------------------------------------------------------------------- Monitor configuration: For adapting StyxMon to new devices, if they are variants of an existing platform (like SA1100), all that should be required is changing the monitor configuration file (such as sword.mcf) The best way to do this is to take an existing functional file and modify the parameters appropriately. Currently, the only monitor configuration files are for the SA1100, so all of the following discussion relates to SA1100 variants. Most parameters can be specified in a variety of ways, either as a full 32-bit value for a configuration register, as a separate bitfield value, or as a clockspeed-independent timing value. - clockspeed set PPCR to the correct multiplier for the desired clockspeed. The actual clockspeed will be OSCHZ*(PPCR*4+16) - DRAM timings MDCNFG can be set to the entire 32-bit register, or MDCNFG_DE, MDCNFG_TRP, etc can all be set to the individual values. If a timing specification is added (i.e. MDCNFG_TDL=15ns) then the correct value will be computed using the current clock speed to ensure that a delay of at least the specified amount occurs. - FLASH/static banks banks with arbitrary names can be initialized by either specifying the whole config value (i.e. SBANK_FLASH=0x4230) or by specifying individual values and timings (i.e. SBANK_FLASH_RDN=58ns) banks with arbitrary names are associated with real banks with assignments such as: SBANK0=FLASH - CAS waveform this, unfortunately, has to be set by hand, and needs to be changed at different clock speeds. The easiest thing to do is to compute it for a given clock speed, and then add a comment about which speed it's for, then comment it out and add a new one for different speeds. This way, the various waveforms for different speeds remain in the file, ready to be used. It's important to remember to uncomment the correct one though. The waveform itself is a binary number of up to 96 bits. If there are less than 96, the remaining ones are assumed to be ones. Zeros can be specified with '.' instead of '0' to make the waveform more visible at a moment's glance. - multiple memory configurations It is possible to have more than one memory configuration loaded into styxmon. At the moment, up to 4 are allowed. This can be extended by editing os/sa1100/monconf.c. Each memory configuration consists of a set of lines like the following: memcfg { ... } Technically, no variables actually need to be specified in the memcfg section. All variables defined at the point of the '}' are considered part of that memcfg. This means that all of them could be defined ahead of time. This also allows "global" values to get shared easily between memory configurations. All global values get declared first, and then in each memcfg{} structure, variables specific to that configuration (such as MDCNFG_ROWS) are given. When StyxMon starts up, it tries all memory configurations, and performs a quick memory test with each. The configuration that yields the most memory is the one that gets picked. This allows different types of DRAM to be plugged into a device, and when the device comes up it tries each and picks the correct one. After it selects one, more thorough memory tests are performed in order to map memory consecutively and determine the total size. - memory mappings the memmap{} structure shouldn't need to be changed, but if it does, follow the example ones, and change the virtual or physical addresses that need to be adjusted, or add new ones. Keep in mind that all mapping is being done on 1MB boundaries. - flash memory base set FLASHBASE to the mapped address of flash (based on the memmap table) - GPIO initialization set GPDR, GAFR, and GPSR to the desired default state for these registers after the monitor successfully initializes. This can be used to turn on LED's to say that the board is okay. - autoboot disable NOAUTO_ADDR,NOAUTO_MASK, and NOAUTO_VAL can be set to the address, mask, and value to check for to disable autoboot. If (*(ulong*)NOAUTO_ADDR & NOAUTO_MASK) == NOAUTO_VAL) then styxmon will override the autoboot and go into "hangout" mode, waiting for a Styx connection. After tuning all of the values and building a monitor, running 'monconf -v ' on the resulting binary will print all of the configuration values in that monitor, and can be used to verify timings, etc.