Linux/MIPS Porting Guide - Revision history

FlorianFainelli: /* The IRQ initialization code */

2013-02-18T16:15:29Z

‎The IRQ initialization code

FlorianFainelli: /* The hw_irq_controller struct */

2013-02-18T16:08:56Z

‎The hw_irq_controller struct

FlorianFainelli: /* Interrupt code overview */

2013-02-18T16:01:58Z

‎Interrupt code overview

FlorianFainelli: /* Provide board-specific hooks */

2013-02-18T15:39:57Z

‎Provide board-specific hooks

FlorianFainelli: /* Set up cascading interrupts */

2013-02-18T15:31:34Z

‎Set up cascading interrupts

FlorianFainelli: /* Supporting a new CPU */

2013-02-18T15:30:08Z

‎Supporting a new CPU

FlorianFainelli: /* Early printk() */

2013-02-18T15:27:25Z

‎Early printk()

FlorianFainelli: /* Configure and build a kernel image */

2013-02-18T15:23:27Z

‎Configure and build a kernel image

FlorianFainelli: /* Provide board-specific hooks */

2013-02-18T15:21:16Z

‎Provide board-specific hooks

FlorianFainelli: /* Hook into the build system */

2013-02-18T15:18:46Z

‎Hook into the build system

@@ Line 403: / Line 403: @@
 === The IRQ initialization code ===
-The IRQ initialization is done in 'init_IRQ()'. Currently it is supplied by each individual board. In the future, it will probably be a MIPS common routine, which will further invoke a board-specific function, board_irq_init(). board_irq_init will be a function pointer that <my_board>_setup() function needs to assign propoer value.
+The IRQ initialization is done in 'arch_init_irq()'. Currently it is supplied by each individual board. In the future, it will probably be a MIPS common routine, which will further invoke a board-specific function, board_irq_init(). board_irq_init will be a function pointer that <my_board>_setup() function needs to assign propoer value.
-In any case, the following is a skeleton code for a normal init_IRQ() routine.
+In any case, the following is a skeleton code for a normal 'arch_init_irq()' routine.
- extern asmlinkage void vr4181_handle_irq(void);
+  static void irq_mask(struct irq_data *d)
- extern void breakpoint(void);
- extern int setup_irq(unsigned int irq, struct irqaction *irqaction);
+         /* clear interrupt at interrupt controller level */
- extern void mips_cpu_irq_init(u32 irq_base);
- extern void init_generic_irq(void);
+  static void irq_unmask(struct irq_data *d)
- static struct irqaction cascade =
-          { no_action, SA_INTERRUPT, 0, "cascade", NULL, NULL };
+         /* set interrupt at interrupt controller level */
- static struct irqaction reserved =
-          { no_action, SA_INTERRUPT, 0, "reserved", NULL, NULL };
- static struct irqaction error_irq =
+  static struct irq_chip my_irq_chip = {
-         { error_action, SA_INTERRUPT, 0, "error", NULL, NULL };
+          .name          = "myirqchip",
+         .irq_mask      = irq_mask,
-  void __init init_IRQ(void)
+          .irq_unmask    = irq_unmask,
+  {
           int i;
   	/* hardware initialization code */
   	....
          /* init all interrupt controllers */
-         mips_cpu_irq_init(CPU_IRQ_BASE);
+         mips_cpu_irq_init();
   	....
          /* set up cascading IRQ */
-         setup_irq(CPU_IRQ_IP3, &cascade);
+        setup_irq(CPU_IRQ_IP3, &cascade);
   	/* set up reserved IRQ so that others can not mistakingly request
   	 * it later.
    	 */
-         setup_irq(CPU_IRQ_IP4, &reserved);
+        setup_irq(CPU_IRQ_IP4, &reserved);
   #ifdef CONFIG_DEBUG
@@ Line 450: / Line 456: @@
   	 * capture it.
   	 */
-         setup_irq(CPU_IRQ_IP4, &error_irq);
+        setup_irq(CPU_IRQ_IP4, &error_irq);
- #endif
-−
- #ifdef CONFIG_REMOTE_DEBUG
-         printk("Setting debug traps - please connect the remote debugger.\n");
-         set_debug_traps();
-         breakpoint();
   #endif
+  }

@@ Line 395: / Line 395: @@
 * You need to expand your interrupt dispatching code properly to identify the added interrupt sources. If the code is simple enough, you can do it in the same int_handler.S file. If it is more complicated, you may do it in a separate C function (such as in the DDB5476 board).
-=== The hw_irq_controller struct ===
+=== The irq_chip struct ===
-The <code>hw_irq_controller</code> structure' is a defined in the 'include/linux/irq.h' file as an alias for the 'hw_interrupt_type' structure.
+The <code>irq_chip</code> structure' is a defined in the 'include/linux/irq.h' file.
- struct hw_interrupt_type {
+The 'arch/mips/kernel/irq_cpu.c' is a good sample code to write 'irq_chip' member functions. Refer to the comments above the definition of 'struct irq_chip' in 'include/linux/irq.h' for more information about each function pointer.
-         const char * typename;
-         unsigned int (*startup)(unsigned int irq);
-         void (*shutdown)(unsigned int irq);
-         void (*enable)(unsigned int irq);
-         void (*disable)(unsigned int irq);
-         void (*ack)(unsigned int irq);
-         void (*end)(unsigned int irq);
-         void (*set_affinity)(unsigned int irq, unsigned long mask);
- };
-−
-The 'arch/mips/kernel/irq_cpu.c' is a good sample code to write 'hw_irq_controller' member functions. Here are some more programming notes for each of these functions:
-−
-* <code>const char * typename;</code>
-Controller name. Will be displayed under /proc/interrupts.
-−
-* <code>unsigned int (*startup)(unsigned int irq);</code>
-Invoked when request_irq() or setup_irq are called. You need to enable this interrupt here. Other than that you may also want to do some IRQ-specific initialization (such as turning on power for this interrupt, perhaps).
-−
-* <code>void (*shutdown)(unsigned int irq);</code>
-Invoked when free_irq() is called. You need to disable this interrupt and perhaps some other IRQ-specific cleanup.
-−
-* <code>void (*enable)(unsigned int irq) and void (*disable)(unsigned int irq)</code>
-They are used to implement enable_irq(), disable_irq() and disable_irq_nosync(), which in turn are used by driver code.
-−
-* <code>void (*ack)(unsigned int irq)</code>
-ack() is invoked at the beginning of do_IRQ() when we want to acknoledge an interrupt. I think you need also to disable this interrupt here so that you don't get recursive interrupts on the same interrupt source. [HELP: can someone confirm?]
-−
-* <code>void (*end)(unsigned int irq)</code>
-This is called by do_IRQ() after it has handled this interrupt. If you disabled interrupt in ack() function, you should enable it here. [HELP: generally what else we should do here?]
-−
-* <code>void (*set_affinity)(unsigned int irq, unsigned long mask)</code>
-This is used in SMP machines to set up interrupt handling affinity with certain CPUs. [TODO] [HELP]
 === The IRQ initialization code ===

@@ Line 346: / Line 346: @@
 * IRQ detection/dispatching:
-This is typically assembly code in a file called 'int_handler.S'. Sometimes there is also secondary-level dispatching code written in C for complicated IRQ detection. The end result is that we identify and select a single IRQ source, represented by an integer, and then pass it to function 'do_IRQ()'.
+This is typically coded in a file called 'irq.c' by the low-level C function <code>plat_irq_dispatch()</code>. This function is called from the assembly defined macro 'handle_int' which is in turn set as the exception vector 0 (interrupts). This 'plat_irq_dispatch' function is responsible for reading the status and cause register and dispatch the interrupt handling to the corresponding interrupt handlers (CPU timer, IP2, IP3 ...)
 * do_IRQ()
 do_IRQ() is provided in the 'arch/mips/kernel/irq.c' file. It provides a common framework for IRQ handling. It invokes the individual IRQ controller code to enable/disable a particular interrupt. It calls the driver supplied interrupt handling routine that does the real processing.
-* hw_irq_handler
+* struct irq_chip
-It is a structure associated with each IRQ source. The structure is a collection of function pointers, which tells do_IRQ() how it should deal with this particular IRQ.
+This structure represents the kernel view of a specific hardware interrupt controller. Some basic function pointers such as 'irq_mask' and 'irq_unmask' are required for basic interrupt operations. For each and every single interrupt line serviced by this controller, you should call 'irq_set_chip_and_handler()' to instruct the Linux kernel on how to service this interrupt within this interrupt controller (interrupt number, level/edge handling, parent interrupt controller). Depending on the hardware features of your interrupt controller (level, edge interrupts, routing ...) you might need to implement more callbacks to properly support its features.
 * driver interrupt handling code
-The code that does the real job.
+The code that does the real job. An interrupt handler within a specific driver is registered and released using 'request_irq()', resp. 'free_irq()' and should implement a driver/device specific interrupt handler function whose prototype is 'irqreturn_t isr_handler(int irq, void *dev_id)'.
-Obviously for our porting purposes we need to write IRQ detection/disptaching code and the hw_irq_handler code for any new IRQ controller used in the system. In addition, there is also IRQ setup and initialization code.
+Obviously for our porting purposes we need to write IRQ detection/disptaching code and the corresponding struct irq_chip function pointers code for any new IRQ controller used in the system. In addition, there is also IRQ setup and initialization code.
 === CPU as an IRQ controller ===

@@ Line 159: / Line 159: @@
 * <code>arch_init_irq()</code>
   /*
    * arch/mips/aloha/irq.c
@@ Line 164: / Line 165: @@
   #include <linux/init.h>
   void __init arch_init_irq(void)

@@ Line 375: / Line 375: @@
 * In your IRQ setup routine, setup the cascading IRQs. This setup will enable interrupts for the upper interrupt controller so that the lower-level interrupts can cascade through once they are enabled. A typical way of doing this is to have a dummy 'irqaction struct' and setup as follows:
-  static struct irqaction cascade =
+  static struct irqaction cascade = {
-         { no_action, SA_INTERRUPT, 0, "cascade", NULL, NULL };
+        .handler        = no_action,
+        .name           = "cascade",
- extern int setup_irq(unsigned int irq, struct irqaction *irqaction);
+        .flags          = IRQF_NO_THREAD,
+  };
   void __init <my>_irq_init(void)
+  {

@@ Line 302: / Line 302: @@
 == Supporting a new CPU ==
-In the MIPS world, there are different families of MIPS cores. For example Toshiba [[TX49XX|TX49]], [[SB1|SiByte SB1]], [[NEC_VR4100|NEC VR41XX]], [[MIPS32]], and [[MIPS64]] to name a few. These different families may have different cache architectures, may be 32-bit or 64-bit, and may or may not have a FP unit. A complete list of families is found in the ''arch/mips/Kconfig'' and ''include/asm-mips/cpu.h'' files. When you are configuring your kernel the complete list will appear under the ''CPU type'' menu selection. If you are adding support for an entirely new family of MIPS cores, you will need to change the following files:
+In the MIPS world, there are different families of MIPS cores. For example Toshiba [[TX49XX|TX49]], [[SB1|SiByte SB1]], [[NEC_VR4100|NEC VR41XX]], [[MIPS32]], and [[MIPS64]] to name a few. These different families may have different cache architectures, may be 32-bit or 64-bit, and may or may not have a FP unit. A complete list of families is found in the ''arch/mips/Kconfig'' and ''arch/mips/include/asm-mips/cpu.h'' files. When you are configuring your kernel the complete list will appear under the ''CPU type'' menu selection. If you are adding support for an entirely new family of MIPS cores, you will need to change the following files:
 * ''arch/mips/Kconfig'': You will need to add your processor family to the list under ''CPU type''.
-* ''include/asm-mip/cpu.h'': You will need to add a <code>PRID_COMP</code> and <code>PRID_IMP</code> entries for your processor family if they do not already exist. You will also need to add the CPU types that you will support in that family. Adding CPU types is covered below.
+* ''arch/mips/include/asm-mip/cpu.h'': You will need to add a <code>PRID_COMP</code> and <code>PRID_IMP</code> entries for your processor family if they do not already exist. You will also need to add the CPU types that you will support in that family. Adding CPU types is covered below.
 * ''arch/mips/kernel/cpu-probe.c'': For each processor family, there is typically a <code>cpu_probe_XXX()</code> function that probes and fills in the <code>struct cpuinfo_mips</code> which contains information about the CPU type, whether a FP unit exists, the number of TLBs available, etc. Your function is responsible for properly probing and filling in this information for the entire family of processors. Finally, if your family does something special for CPU idle, then you will have to define a <code>wait()</code> function. Most likely, you will be able to use one that already exists. If not, add your <code>wait()</code> function and enable detection of it in <code>check_wait()</code>.
@@ Line 312: / Line 312: @@
 * ''arch/mips/mm'': If your processor family has a unique cache architecture or anything out of the ordinary, you will need to either add or modify files in this directory.
-Within each family of MIPS cores, there are multiple processors. For example, Alchemy processors and Broadcom processors are in the MIPS32 family, the Sibyte 1250 is in the SB1 family, and so on. Once you have decided what family your processor is in, you need to verify that a unique CPU identification exists for it. ''include/asm-mips/cpu.h'' contains all of the currently supported CPU types for the Linux/MIPS kernel.
+Within each family of MIPS cores, there are multiple processors. For example, Alchemy processors and Broadcom processors are in the MIPS32 family, the Sibyte 1250 is in the SB1 family, and so on. Once you have decided what family your processor is in, you need to verify that a unique CPU identification exists for it. ''arch/mips/include/asm-mips/cpu.h'' contains all of the currently supported CPU types for the Linux/MIPS kernel.
-If your processor is already listed in ''include/asm-mips/cpu.h'', the existing Linux/MIPS code should auto-detect it. Otherwise, you'll need to change three files to properly detect your processor:
+If your processor is already listed in ''arch/mips/include/asm-mips/cpu.h'', the existing Linux/MIPS code should auto-detect it. Otherwise, you'll need to change three files to properly detect your processor:
-* ''include/asm-mips/cpu.h'': Add your processor at the end of the <code>CPU_XXX</code> definitions. Make sure you update the <code>CPU_LAST</code> value to match that of the processor you added.
+* ''arch/mips/include/asm-mips/cpu.h'': Add your processor at the end of the <code>CPU_XXX</code> definitions. Make sure you update the <code>CPU_LAST</code> value to match that of the processor you added.
 * ''arch/mips/kernel/proc.c'': Add an entry to the <code>cpu_name</code> array so that your CPU name can be properly displayed in /proc/cpuinfo.
 * ''arch/mips/kernel/cpu-probe.c'': Add your processor into the case statement in the function <code>check_wait()</code> if your CPU can do some sort of wait or idle operation. Add the necessary code in the <code>cpu_probe_XXX()</code> function to detect and set your CPU type.

@@ Line 227: / Line 227: @@
 Unfortunately, setup of the serial console happens much later during the kernel startup process. (See [[#Appendix A: Linux startup sequence in 2.4.x|Appendix A: Linux startup sequence in 2.4.x]] for a chart of the kernel start-up sequence). Chances are your new kernel probably dies even before that. That is where the early printk patch comes in handy. It allows you to see printk as early as the first line of C code.
-By the way the first line of C code for Linux MIPS is the first line of code of 'init_arch()' function in the 'arch/mips/setup.c' file.
+In order to properly make use of early printk, your platform should select <code>SYS_HAS_EARLY_PRINTK</code> and implement a <code>prom_putchar()</code> routine which will be used by the kernel to output characters via the UART.
-−
-For kernel version earlier than 2.4.10, you can find the [http://linux.junsun.net/porting-howto/patches/early-printk.patch early printk patch] here for boards with standard UART serial ports. Starting from 2.4.10 and beyond, [http://linux.junsun.net/porting-howto/patches/early-printk-2.4.10+.patch a new printk patch] is needed. If you have already got the stand-alone "Hello, world!" program running, the early printk should be easy to get going, and you should have printk output from the Linux kernel very soon.
 == Serial driver and console ==

@@ Line 208: / Line 208: @@
 * Select the right CPU. Under 'CPU selection' select your CPU. If there is no entry for the CPU on your board, you will need to add support for it. Most recent CPUs can generally run to some degree with CPU_R4X00.
 * Under 'Character devices', select 'Standard/generic (8250/16550 and compatible UARTs) serial support' and 'Support for console on serial port'. Unselect the 'Virtual terminal' option.
 * Under the 'Kernel hacking' option, select 'Are you using a crosscompiler'.
 * For other options either take the default or select 'no'.

@@ Line 188: / Line 188: @@
+  }
-* <code>plat_setup()</code>
+* <code>plat_mem_setup()</code>
   /*
@@ Line 196: / Line 196: @@
   #include <linux/init.h>
-  void __init plat_setup(void)
+  void __init plat_mem_setup(void)
+  {
           /* do board-specific setup.. */
+  }
 === Configure and build a kernel image ===

@@ Line 121: / Line 121: @@
           select ARC
-You'll need a corresponding Makefile entry so <code>make</code> may recurse into your platform sub-directory.
+You'll need a corresponding Makefile entry so <code>make</code> may recurse into your platform sub-directory. Such a Makefile would look like this:
 <code>$(load-y)</code> is the starting address for your Linux image when it is loaded into RAM. Note that the first <code>0x200</code> bytes are used by the exception vectors on most CPUs. Some CPUs will require a larger space, so modify <code>$(load-y)</code> accordingly. Due to the linker's addressing limit, the start address is aligned on a 8KB boundary, so setting <code>$(load-y)</code> to <code>0xffffffff80002000</code> should be reasonable:
-  --- a/arch/mips/Makefile
+  --- a/arch/mips/aloha/Platform
-  +++ b/arch/mips/Makefile
+  +++ b/arch/mips/aloha/Platform
- @@ -401,6 +401,12 @@ core-$(CONFIG_MIPS_IVR)            += arch/mips/it
-  load-$(CONFIG_MIPS_IVR)                += 0xffffffff80100000
-−
-−
- +# Hawaii Aloha board
   +#
-  +core-$(CONFIG_HAWAII_ALOHA)    += arch/mips/aloha/
+  +# Hawaii Aloha board
- +load-$(CONFIG_HAWAII_ALOHA)    += 0xffffffff80002000
-−
   +#
-  # ITE 8172 eval board with QED 5231 CPU
+ +platform-$(CONFIG_HAWAII_ALOHA) += aloha/
+ +cflags-$(CONFIG_HAWAII_ALOHA)   += -I$(srctree)/arch/mips/include/asm/mach-aloha/
-  core-$(CONFIG_MIPS_ITE8172)    += arch/mips/ite-boards/qed-4n-s01b/
+ +load-$(CONFIG_HAWAII_ALOHA)     += 0xffffffff80002000
 === Provide board-specific hooks ===