arch/architecture.dox

   1 /** @page dev_architecture Integrate a new architecture (ARCH)
   2
   3 @section linker_scripts Rules for the generic Linker Script File
   4
   5 Never include an object file by name directly! Linker Script Files defines the
   6 layout, not the content. Content is defined in objecfiles instead.
   7
   8 Don't rely on the given object file order to create your binary U-Boot v2! This
   9 may work, but is not relyable in all cases (and its a very bad style)!
  10
  11 For the special case some layout contraints exists, use specific section
  12 naming instead. Refer @ref reset_code how to define this specific section.
  13
  14 @section reset_code Bring it up: The Reset Code
  15
  16 The way a CPU wakes up after reset is very specific to its architecture.
  17
  18 For example the ARM architecture starts its reset code at address 0x0000000,
  19 the x86 architecture at 0x000FFFF0, PowerPC at 0x00000100 or 0xFFFFF100.
  20
  21 So for the special reset code on all architectures it must be located at
  22 architecture specific locations within the binary U-Boot image.
  23
  24 All reset code uses section ".text_entry" for its localisation within the
  25 binary U-Boot image. Its up to the linker script file to use this section name
  26 to find the right place in whatever environment and U-Boot sizes.
  27
  28 @code
  29         .section ".text_entry","ax"
  30 @endcode
  31
  32 @section arch_files List of changes
  33
  34  - create a new subdirectory in /arch
  35 TODO
  36
  37 */
  38
  39 /** @page dev_cpu Integrate a new CPU (MACH)
  40
  41 Features required for every CPU:
  42
  43  - clocksource
  44  - CPU reset function
  45
  46 @section time_keeping Time keeping
  47
  48 In U-Boot-v2 we are using the clocksource mechanism from the Linux Kernel.
  49 This makes it fairly easy to add timer functionality for a new board or
  50 architecture.
  51
  52 Apart from initialization there is only one function to be registerd:
  53 clocksource_read(). This function returns the current value of a free running
  54 counter. Other functions like udelay() and get_time_ns() are derived from this
  55 function. The only thing you have to implement is a clocksource driver and
  56 to register it at runtime.
  57
  58 @code
  59 static uint64_t mycpu_clocksource_read(void)
  60 {
  61         TODO
  62 }
  63
  64 static struct clocksource cs = {
  65         .read   = mycpu_clocksource_read,
  66         .mask   = 0xffffffff,
  67         .shift  = 10,
  68 };
  69
  70 ....
  71         init_clock(&cs);
  72 ....
  73 @endcode
  74
  75 See arch/arm/mach-imx/clocksource.c for an example. clocksource drivers from
  76 the Linux Kernel can be used nearly 1:1, except for the register accesses.
  77
  78 Note: For clocksources the __lshrdi3 symbol is needed. You can find the
  79 function for your architecture in the Linux Kernel or a libc of your choice.
  80
  81 Note: U-Boot-v2 expects an upward counting counter!
  82
  83 @section reset_function Reset function
  84
  85 TODO
  86
  87 @li @subpage dev_arm_mach
  88 @li @subpage dev_bf_mach
  89 @li @subpage dev_ppc_mach
  90
  91 */
  92
  93 /** @page io_access_functions I/O access functions
  94
  95 List of functions to be used for hardware register access (I/O).
  96
  97 @section native_access Native IN/OUT access
  98
  99 @note Native means: It uses the same endianess than the CPU.
 100
 101 @subsection single_native_access Single access of various width
 102
 103 The following functions are intended to be used for a single I/O access.
 104
 105 To read a byte (8 bit) from a specific I/O address:
 106 @code
 107 uint8_t readb(unsigned long)
 108 @endcode
 109
 110 To read a word (16 bit) from a specific I/O address:
 111 @code
 112 uint16_t readw(unsigned long)
 113 @endcode
 114
 115 To read a long word (32 bit) from a specific I/O address:
 116 @code
 117 uint32_t readl(unsigned long)
 118 @endcode
 119
 120 To write a byte (8 bit) into a specific I/O address:
 121 @code
 122 void writeb(uint8_t val, unsigned long)
 123 @endcode
 124
 125 To write a word (16 bit) into a specific I/O address:
 126 @code
 127 void writew(uint16_t val, unsigned long)
 128 @endcode
 129
 130 To write a long word (32 bit) into a specific I/O address:
 131 @code
 132 void writel(uint32_t val, unsigned long)
 133 @endcode
 134
 135 @subsection string_native_access String native access of various width
 136
 137 The following functions are intended to be used for string based I/O access.
 138
 139 To read a string of bytes (8 bit) from one specific I/O address:
 140 @code
 141 void readsb(const void __iomem *addr, void *mem_buffer, int byte_count);
 142 @endcode
 143
 144 To read a string of words (16 bit) from one specific I/O address:
 145 @code
 146 void readsw(const void __iomem *addr, void *mem_buffer, int word_count);
 147 @endcode
 148
 149 To read a string of long words (32 bit) from one specific I/O address:
 150 @code
 151 void readsl(const void __iomem *addr, void *mem_buffer, int long_count);
 152 @endcode
 153
 154 To write a string of bytes (8 bit) to one specific I/O address:
 155 @code
 156 void writesb(void __iomem *addr, const void *mem_buffer, int byte_count);
 157 @endcode
 158
 159 To write a string of words (16 bit) to one specific I/O address:
 160 @code
 161 void writesw(void __iomem *addr, const void *mem_buffer, int word_count);
 162 @endcode
 163
 164 To write a string of long words (32 bit) to one specific I/O address:
 165 @code
 166 void writesl(void __iomem *addr, const void *mem_buffer, int long_count);
 167 @endcode
 168
 169 @section special_access Special IN/OUT access
 170
 171 TBD
 172
 173 */