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 @a barebox! 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 @a barebox image.
  23
  24 All reset code uses section ".text_entry" for its localisation within the
  25 binary @a barebox image. Its up to the linker script file to use this section name
  26 to find the right place in whatever environment and @a barebox 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 @a barebox 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 @a barebox 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 @li @subpage dev_m68k_mach
  91 @li @subpage dev_x86_mach
  92
  93 */
  94
  95 /** @page io_access_functions I/O access functions
  96
  97 List of functions to be used for hardware register access (I/O).
  98
  99 @section native_access Native IN/OUT access
 100
 101 @note Native means: It uses the same endianess than the CPU.
 102
 103 @subsection single_native_access Single access of various width
 104
 105 The following functions are intended to be used for a single I/O access.
 106
 107 To read a byte (8 bit) from a specific I/O address:
 108 @code
 109 uint8_t readb(unsigned long)
 110 @endcode
 111
 112 To read a word (16 bit) from a specific I/O address:
 113 @code
 114 uint16_t readw(unsigned long)
 115 @endcode
 116
 117 To read a long word (32 bit) from a specific I/O address:
 118 @code
 119 uint32_t readl(unsigned long)
 120 @endcode
 121
 122 To write a byte (8 bit) into a specific I/O address:
 123 @code
 124 void writeb(uint8_t val, unsigned long)
 125 @endcode
 126
 127 To write a word (16 bit) into a specific I/O address:
 128 @code
 129 void writew(uint16_t val, unsigned long)
 130 @endcode
 131
 132 To write a long word (32 bit) into a specific I/O address:
 133 @code
 134 void writel(uint32_t val, unsigned long)
 135 @endcode
 136
 137 @subsection string_native_access String native access of various width
 138
 139 The following functions are intended to be used for string based I/O access.
 140
 141 To read a string of bytes (8 bit) from one specific I/O address:
 142 @code
 143 void readsb(const void __iomem *addr, void *mem_buffer, int byte_count);
 144 @endcode
 145
 146 To read a string of words (16 bit) from one specific I/O address:
 147 @code
 148 void readsw(const void __iomem *addr, void *mem_buffer, int word_count);
 149 @endcode
 150
 151 To read a string of long words (32 bit) from one specific I/O address:
 152 @code
 153 void readsl(const void __iomem *addr, void *mem_buffer, int long_count);
 154 @endcode
 155
 156 To write a string of bytes (8 bit) to one specific I/O address:
 157 @code
 158 void writesb(void __iomem *addr, const void *mem_buffer, int byte_count);
 159 @endcode
 160
 161 To write a string of words (16 bit) to one specific I/O address:
 162 @code
 163 void writesw(void __iomem *addr, const void *mem_buffer, int word_count);
 164 @endcode
 165
 166 To write a string of long words (32 bit) to one specific I/O address:
 167 @code
 168 void writesl(void __iomem *addr, const void *mem_buffer, int long_count);
 169 @endcode
 170
 171 @section special_access Special IN/OUT access
 172
 173 TBD
 174
 175 */