libgloss/or1k/boards/README

   1 # Add a new board
   2
   3 Before adding a new board, you may consider if your board can use another
   4 board definition and simply overwrite the weak symbols.
   5
   6 If you think it is worth adding a new board, you need to perform the following
   7 steps:
   8
   9  * Decide for a meaningful board name (refered to as <board> below). It should
  10    be specific enough (not openrisc..), but be rather generic if it may cover
  11    similar boards as well.
  12
  13  * Create a file <board>.S (assembler) or <board>.c (C). Of course, C is easier
  14    to write and you can implement everything in C, but there are restrictions:
  15
  16     * There is an early initialization function. It is called before the C
  17       library and even the stack are initialized. A default implementation skips
  18       this step, so everything will compile, but if you really need
  19       initialization that early you are bound to assembly language.
  20
  21     * You essentially should not use the C library functions as this may lead to
  22       link issues and circular dependencies.
  23
  24    You can copy board_tmpl.S or board_tmpl.c as starting point for your board.
  25
  26  * The following symbols must be defined in your board file:
  27
  28     * _or1k_board_mem_base: Memory base address
  29
  30     * _or1k_board_mem_size: Memory size
  31
  32     * _or1k_board_clk_freq: Clock frequency
  33
  34     * _or1k_board_uart_base: UART base address. Set to 0 if no UART present.
  35
  36     * _or1k_board_uart_baud: UART baud rate. Only used if UART base is > 0
  37
  38     * _or1k_board_uart_IRQ: UART interrupt line. Only used if UART base is > 0
  39
  40    You can define a weak attribute for all of the symbols so that they can
  41    be overwritten by the user (more flexibility).
  42
  43  * The following functions need to be implemented:
  44
  45    * _or1k_board_init: Is called after C library initialization and UART
  46        initialization.
  47
  48    * _or1k_board_exit: Is called after the program has exited and the C library
  49        finished all deconstructions etc.
  50
  51    Similar to the symbols you can define those functions weak.
  52
  53  * The following functions can be implemented:
  54
  55    * _or1k_board_init_early: Only in assembly (see above). Is called before
  56        anything is initialized, not even the stack! You can use all registers
  57        in this function. The default implementation in crt0.S skips this step,
  58        which is fine in most cases. If you decide to implement it, you need to
  59        define it with the global attribute to overwrite the default
  60        implementation. It is recommended to do so in assembler board files to
  61        keep the ability to overwrite the default implementation by the user.
  62
  63 When you are done with your board, add it to libgloss/or1k/Makefile.inc like the
  64 other libboard-*.a definitions and compile.