diff options
Diffstat (limited to 'Documentation/sh')
| -rw-r--r-- | Documentation/sh/clk.txt | 32 | ||||
| -rw-r--r-- | Documentation/sh/kgdb.txt | 179 | ||||
| -rw-r--r-- | Documentation/sh/new-machine.txt | 278 | ||||
| -rw-r--r-- | Documentation/sh/register-banks.txt | 33 |
4 files changed, 522 insertions, 0 deletions
diff --git a/Documentation/sh/clk.txt b/Documentation/sh/clk.txt new file mode 100644 index 0000000..114b595 --- /dev/null +++ b/Documentation/sh/clk.txt @@ -0,0 +1,32 @@ +Clock framework on SuperH architecture + +The framework on SH extends existing API by the function clk_set_rate_ex, +which prototype is as follows: + + clk_set_rate_ex (struct clk *clk, unsigned long rate, int algo_id) + +The algo_id parameter is used to specify algorithm used to recalculate clocks, +adjanced to clock, specified as first argument. It is assumed that algo_id==0 +means no changes to adjanced clock + +Internally, the clk_set_rate_ex forwards request to clk->ops->set_rate method, +if it is present in ops structure. The method should set the clock rate and adjust +all needed clocks according to the passed algo_id. +Exact values for algo_id are machine-dependent. For the sh7722, the following +values are defined: + + NO_CHANGE = 0, + IUS_N1_N1, /* I:U = N:1, U:Sh = N:1 */ + IUS_322, /* I:U:Sh = 3:2:2 */ + IUS_522, /* I:U:Sh = 5:2:2 */ + IUS_N11, /* I:U:Sh = N:1:1 */ + SB_N1, /* Sh:B = N:1 */ + SB3_N1, /* Sh:B3 = N:1 */ + SB3_32, /* Sh:B3 = 3:2 */ + SB3_43, /* Sh:B3 = 4:3 */ + SB3_54, /* Sh:B3 = 5:4 */ + BP_N1, /* B:P = N:1 */ + IP_N1 /* I:P = N:1 */ + +Each of these constants means relation between clocks that can be set via the FRQCR +register diff --git a/Documentation/sh/kgdb.txt b/Documentation/sh/kgdb.txt new file mode 100644 index 0000000..05b4ba8 --- /dev/null +++ b/Documentation/sh/kgdb.txt @@ -0,0 +1,179 @@ + +This file describes the configuration and behavior of KGDB for the SH +kernel. Based on a description from Henry Bell <henry.bell@st.com>, it +has been modified to account for quirks in the current implementation. + +Version +======= + +This version of KGDB was written for 2.4.xx kernels for the SH architecture. +Further documentation is available from the linux-sh project website. + + +Debugging Setup: Host +====================== + +The two machines will be connected together via a serial line - this +should be a null modem cable i.e. with a twist. + +On your DEVELOPMENT machine, go to your kernel source directory and +build the kernel, enabling KGDB support in the "kernel hacking" section. +This includes the KGDB code, and also makes the kernel be compiled with +the "-g" option set -- necessary for debugging. + +To install this new kernel, use the following installation procedure. + +Decide on which tty port you want the machines to communicate, then +cable them up back-to-back using the null modem. On the DEVELOPMENT +machine, you may wish to create an initialization file called .gdbinit +(in the kernel source directory or in your home directory) to execute +commonly-used commands at startup. + +A minimal .gdbinit might look like this: + + file vmlinux + set remotebaud 115200 + target remote /dev/ttyS0 + +Change the "target" definition so that it specifies the tty port that +you intend to use. Change the "remotebaud" definition to match the +data rate that you are going to use for the com line (115200 is the +default). + +Debugging Setup: Target +======================== + +By default, the KGDB stub will communicate with the host GDB using +ttySC1 at 115200 baud, 8 databits, no parity; these defaults can be +changed in the kernel configuration. As the kernel starts up, KGDB will +initialize so that breakpoints, kernel segfaults, and so forth will +generally enter the debugger. + +This behavior can be modified by including the "kgdb" option in the +kernel command line; this option has the general form: + + kgdb=<ttyspec>,<action> + +The <ttyspec> indicates the port to use, and can optionally specify +baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200". + +The <action> can be "halt" or "disabled". The "halt" action enters the +debugger via a breakpoint as soon as kgdb is initialized; the "disabled" +action causes kgdb to ignore kernel segfaults and such until explicitly +entered by a breakpoint in the code or by external action (sysrq or NMI). + +(Both <ttyspec> and <action> can appear alone, w/o the separating comma.) + +For example, if you wish to debug early in kernel startup code, you +might specify the halt option: + + kgdb=halt + +Boot the TARGET machine, which will appear to hang. + +On your DEVELOPMENT machine, cd to the source directory and run the gdb +program. (This is likely to be a cross GDB which runs on your host but +is built for an SH target.) If everything is working correctly you +should see gdb print out a few lines indicating that a breakpoint has +been taken. It will actually show a line of code in the target kernel +inside the gdbstub activation code. + +NOTE: BE SURE TO TERMINATE OR SUSPEND any other host application which +may be using the same serial port (for example, a terminal emulator you +have been using to connect to the target boot code.) Otherwise, data +from the target may not all get to GDB! + +You can now use whatever gdb commands you like to set breakpoints. +Enter "continue" to start your target machine executing again. At this +point the target system will run at full speed until it encounters +your breakpoint or gets a segment violation in the kernel, or whatever. + +Serial Ports: KGDB, Console +============================ + +This version of KGDB may not gracefully handle conflict with other +drivers in the kernel using the same port. If KGDB is configured on the +same port (and with the same parameters) as the kernel console, or if +CONFIG_SH_KGDB_CONSOLE is configured, things should be fine (though in +some cases console messages may appear twice through GDB). But if the +KGDB port is not the kernel console and used by another serial driver +which assumes different serial parameters (e.g. baud rate) KGDB may not +recover. + +Also, when KGDB is entered via sysrq-g (requires CONFIG_KGDB_SYSRQ) and +the kgdb port uses the same port as the console, detaching GDB will not +restore the console to working order without the port being re-opened. + +Another serious consequence of this is that GDB currently CANNOT break +into KGDB externally (e.g. via ^C or <BREAK>); unless a breakpoint or +error is encountered, the only way to enter KGDB after the initial halt +(see above) is via NMI (CONFIG_KGDB_NMI) or sysrq-g (CONFIG_KGDB_SYSRQ). + +Code is included for the basic Hitachi Solution Engine boards to allow +the use of ttyS0 for KGDB if desired; this is less robust, but may be +useful in some cases. (This cannot be selected using the config file, +but only through the kernel command line, e.g. "kgdb=ttyS0", though the +configured defaults for baud rate etc. still apply if not overridden.) + +If gdbstub Does Not Work +======================== + +If it doesn't work, you will have to troubleshoot it. Do the easy +things first like double checking your cabling and data rates. You +might try some non-kernel based programs to see if the back-to-back +connection works properly. Just something simple like cat /etc/hosts +/dev/ttyS0 on one machine and cat /dev/ttyS0 on the other will tell you +if you can send data from one machine to the other. There is no point +in tearing out your hair in the kernel if the line doesn't work. + +If you need to debug the GDB/KGDB communication itself, the gdb commands +"set debug remote 1" and "set debug serial 1" may be useful, but be +warned: they produce a lot of output. + +Threads +======= + +Each process in a target machine is seen as a gdb thread. gdb thread related +commands (info threads, thread n) can be used. CONFIG_KGDB_THREAD must +be defined for this to work. + +In this version, kgdb reports PID_MAX (32768) as the process ID for the +idle process (pid 0), since GDB does not accept 0 as an ID. + +Detaching (exiting KGDB) +========================= + +There are two ways to resume full-speed target execution: "continue" and +"detach". With "continue", GDB inserts any specified breakpoints in the +target code and resumes execution; the target is still in "gdb mode". +If a breakpoint or other debug event (e.g. NMI) happens, the target +halts and communicates with GDB again, which is waiting for it. + +With "detach", GDB does *not* insert any breakpoints; target execution +is resumed and GDB stops communicating (does not wait for the target). +In this case, the target is no longer in "gdb mode" -- for example, +console messages no longer get sent separately to the KGDB port, or +encapsulated for GDB. If a debug event (e.g. NMI) occurs, the target +will re-enter "gdb mode" and will display this fact on the console; you +must give a new "target remote" command to gdb. + +NOTE: TO AVOID LOSSING CONSOLE MESSAGES IN CASE THE KERNEL CONSOLE AND +KGDB USING THE SAME PORT, THE TARGET WAITS FOR ANY INPUT CHARACTER ON +THE KGDB PORT AFTER A DETACH COMMAND. For example, after the detach you +could start a terminal emulator on the same host port and enter a <cr>; +however, this program must then be terminated or suspended in order to +use GBD again if KGDB is re-entered. + + +Acknowledgements +================ + +This code was mostly generated by Henry Bell <henry.bell@st.com>; +largely from KGDB by Amit S. Kale <akale@veritas.com> - extracts from +code by Glenn Engel, Jim Kingdon, David Grothe <dave@gcom.com>, Tigran +Aivazian <tigran@sco.com>, William Gatliff <bgat@open-widgets.com>, Ben +Lee, Steve Chamberlain and Benoit Miller <fulg@iname.com> are also +included. + +Jeremy Siegel +<jsiegel@mvista.com> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt new file mode 100644 index 0000000..f035416 --- /dev/null +++ b/Documentation/sh/new-machine.txt @@ -0,0 +1,278 @@ + + Adding a new board to LinuxSH + ================================ + + Paul Mundt <lethal@linux-sh.org> + +This document attempts to outline what steps are necessary to add support +for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This +also attempts to outline some of the noticeable changes between the 2.4 +and the 2.5/2.6 SH backend. + +1. New Directory Structure +========================== + +The first thing to note is the new directory structure. Under 2.4, most +of the board-specific code (with the exception of stboards) ended up +in arch/sh/kernel/ directly, with board-specific headers ending up in +include/asm-sh/. For the new kernel, things are broken out by board type, +companion chip type, and CPU type. Looking at a tree view of this directory +hierarchy looks like the following: + +Board-specific code: + +. +|-- arch +| `-- sh +| `-- boards +| |-- adx +| | `-- board-specific files +| |-- bigsur +| | `-- board-specific files +| | +| ... more boards here ... +| +`-- include + `-- asm-sh + |-- adx + | `-- board-specific headers + |-- bigsur + | `-- board-specific headers + | + .. more boards here ... + +Next, for companion chips: +. +`-- arch + `-- sh + `-- cchips + `-- hd6446x + `-- hd64461 + `-- cchip-specific files + +... and so on. Headers for the companion chips are treated the same way as +board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the +hd64461-specific headers. + +Finally, CPU family support is also abstracted: +. +|-- arch +| `-- sh +| |-- kernel +| | `-- cpu +| | |-- sh2 +| | | `-- SH-2 generic files +| | |-- sh3 +| | | `-- SH-3 generic files +| | `-- sh4 +| | `-- SH-4 generic files +| `-- mm +| `-- This is also broken out per CPU family, so each family can +| have their own set of cache/tlb functions. +| +`-- include + `-- asm-sh + |-- cpu-sh2 + | `-- SH-2 specific headers + |-- cpu-sh3 + | `-- SH-3 specific headers + `-- cpu-sh4 + `-- SH-4 specific headers + +It should be noted that CPU subtypes are _not_ abstracted. Thus, these still +need to be dealt with by the CPU family specific code. + +2. Adding a New Board +===================== + +The first thing to determine is whether the board you are adding will be +isolated, or whether it will be part of a family of boards that can mostly +share the same board-specific code with minor differences. + +In the first case, this is just a matter of making a directory for your +board in arch/sh/boards/ and adding rules to hook your board in with the +build system (more on this in the next section). However, for board families +it makes more sense to have a common top-level arch/sh/boards/ directory +and then populate that with sub-directories for each member of the family. +Both the Solution Engine and the hp6xx boards are an example of this. + +After you have setup your new arch/sh/boards/ directory, remember that you +should also add a directory in include/asm-sh for headers localized to this +board (if there are going to be more than one). In order to interoperate +seamlessly with the build system, it's best to have this directory the same +as the arch/sh/boards/ directory name, though if your board is again part of +a family, the build system has ways of dealing with this (via incdir-y +overloading), and you can feel free to name the directory after the family +member itself. + +There are a few things that each board is required to have, both in the +arch/sh/boards and the include/asm-sh/ hierarchy. In order to better +explain this, we use some examples for adding an imaginary board. For +setup code, we're required at the very least to provide definitions for +get_system_type() and platform_setup(). For our imaginary board, this +might look something like: + +/* + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board + */ +#include <linux/init.h> +#include <asm/rtc.h> /* for board_time_init() */ + +const char *get_system_type(void) +{ + return "FooTech Vaporboard"; +} + +int __init platform_setup(void) +{ + /* + * If our hardware actually existed, we would do real + * setup here. Though it's also sane to leave this empty + * if there's no real init work that has to be done for + * this board. + */ + + /* + * Presume all FooTech boards have the same broken timer, + * and also presume that we've defined foo_timer_init to + * do something useful. + */ + board_time_init = foo_timer_init; + + /* Start-up imaginary PCI ... */ + + /* And whatever else ... */ + + return 0; +} + +Our new imaginary board will also have to tie into the machvec in order for it +to be of any use. + +machvec functions fall into a number of categories: + + - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc). + - I/O mapping functions (ioport_map, ioport_unmap, etc). + - a 'heartbeat' function. + - PCI and IRQ initialization routines. + - Consistent allocators (for boards that need special allocators, + particularly for allocating out of some board-specific SRAM for DMA + handles). + +There are machvec functions added and removed over time, so always be sure to +consult include/asm-sh/machvec.h for the current state of the machvec. + +The kernel will automatically wrap in generic routines for undefined function +pointers in the machvec at boot time, as machvec functions are referenced +unconditionally throughout most of the tree. Some boards have incredibly +sparse machvecs (such as the dreamcast and sh03), whereas others must define +virtually everything (rts7751r2d). + +Adding a new machine is relatively trivial (using vapor as an example): + +If the board-specific definitions are quite minimalistic, as is the case for +the vast majority of boards, simply having a single board-specific header is +sufficient. + + - add a new file include/asm-sh/vapor.h which contains prototypes for + any machine specific IO functions prefixed with the machine name, for + example vapor_inb. These will be needed when filling out the machine + vector. + + Note that these prototypes are generated automatically by setting + __IO_PREFIX to something sensible. A typical example would be: + + #define __IO_PREFIX vapor + #include <asm/io_generic.h> + + somewhere in the board-specific header. Any boards being ported that still + have a legacy io.h should remove it entirely and switch to the new model. + + - Add machine vector definitions to the board's setup.c. At a bare minimum, + this must be defined as something like: + + struct sh_machine_vector mv_vapor __initmv = { + .mv_name = "vapor", + }; + ALIAS_MV(vapor) + + - finally add a file arch/sh/boards/vapor/io.c, which contains definitions of + the machine specific io functions (if there are enough to warrant it). + +3. Hooking into the Build System +================================ + +Now that we have the corresponding directories setup, and all of the +board-specific code is in place, it's time to look at how to get the +whole mess to fit into the build system. + +Large portions of the build system are now entirely dynamic, and merely +require the proper entry here and there in order to get things done. + +The first thing to do is to add an entry to arch/sh/Kconfig, under the +"System type" menu: + +config SH_VAPOR + bool "Vapor" + help + select Vapor if configuring for a FooTech Vaporboard. + +next, this has to be added into arch/sh/Makefile. All boards require a +machdir-y entry in order to be built. This entry needs to be the name of +the board directory as it appears in arch/sh/boards, even if it is in a +sub-directory (in which case, all parent directories below arch/sh/boards/ +need to be listed). For our new board, this entry can look like: + +machdir-$(CONFIG_SH_VAPOR) += vapor + +provided that we've placed everything in the arch/sh/boards/vapor/ directory. + +Next, the build system assumes that your include/asm-sh directory will also +be named the same. If this is not the case (as is the case with multiple +boards belonging to a common family), then the directory name needs to be +implicitly appended to incdir-y. The existing code manages this for the +Solution Engine and hp6xx boards, so see these for an example. + +Once that is taken care of, it's time to add an entry for the mach type. +This is done by adding an entry to the end of the arch/sh/tools/mach-types +list. The method for doing this is self explanatory, and so we won't waste +space restating it here. After this is done, you will be able to use +implicit checks for your board if you need this somewhere throughout the +common code, such as: + + /* Make sure we're on the FooTech Vaporboard */ + if (!mach_is_vapor()) + return -ENODEV; + +also note that the mach_is_boardname() check will be implicitly forced to +lowercase, regardless of the fact that the mach-types entries are all +uppercase. You can read the script if you really care, but it's pretty ugly, +so you probably don't want to do that. + +Now all that's left to do is providing a defconfig for your new board. This +way, other people who end up with this board can simply use this config +for reference instead of trying to guess what settings are supposed to be +used on it. + +Also, as soon as you have copied over a sample .config for your new board +(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a +build target, and it will be implicitly listed as such in the help text. + +Looking at the 'make help' output, you should now see something like: + +Architecture specific targets (sh): + zImage - Compressed kernel image (arch/sh/boot/zImage) + adx_defconfig - Build for adx + cqreek_defconfig - Build for cqreek + dreamcast_defconfig - Build for dreamcast +... + vapor_defconfig - Build for vapor + +which then allows you to do: + +$ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux + +which will in turn copy the defconfig for this board, run it through +oldconfig (prompting you for any new options since the time of creation), +and start you on your way to having a functional kernel for your new +board. diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.txt new file mode 100644 index 0000000..a6719f2 --- /dev/null +++ b/Documentation/sh/register-banks.txt @@ -0,0 +1,33 @@ + Notes on register bank usage in the kernel + ========================================== + +Introduction +------------ + +The SH-3 and SH-4 CPU families traditionally include a single partial register +bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families +may have more full-featured banking or simply no such capabilities at all. + +SR.RB banking +------------- + +In the case of this type of banking, banked registers are mapped directly to +r0 ... r7 if SR.RB is set to the bank we are interested in, otherwise ldc/stc +can still be used to reference the banked registers (as r0_bank ... r7_bank) +when in the context of another bank. The developer must keep the SR.RB value +in mind when writing code that utilizes these banked registers, for obvious +reasons. Userspace is also not able to poke at the bank1 values, so these can +be used rather effectively as scratch registers by the kernel. + +Presently the kernel uses several of these registers. + + - r0_bank, r1_bank (referenced as k0 and k1, used for scratch + registers when doing exception handling). + - r2_bank (used to track the EXPEVT/INTEVT code) + - Used by do_IRQ() and friends for doing irq mapping based off + of the interrupt exception vector jump table offset + - r6_bank (global interrupt mask) + - The SR.IMASK interrupt handler makes use of this to set the + interrupt priority level (used by local_irq_enable()) + - r7_bank (current) + |
