Two stage load of ibl from I2C
[keystone-rtos/ibl.git] / src / ibl.h
1 /********************************************************************************************************
2  * FILE PURPOSE: IBL configuration and control definitions
3  ********************************************************************************************************
4  * FILE NAME: ibl.h
5  *
6  * DESCRIPTION: Defines the data structure used to handle initial configuration and control
7  *                              of the ibl. This data structure resides at a fixed location in the device memory
8  *                              map. It is initially populated either during the rom boot. The table can be
9  *                              over-written during the ibl process to redirect the boot. For example the ibl
10  *                              can initially load from an i2c which repopulates this table with parameters
11  *                              for an ethernet boot.
12  *
13  *  @file  ibl.h
14  *
15  *  @brief
16  *      This file defines the configuration and control of the IBL
17  *  
18  *
19  ********************************************************************************************************/
20 #ifndef IBL_H
21 #define IBL_H
23 #include "types.h"
25 /* Information used to make generate a bootp request */
26 /**
27  * @brief
28  *    Defines parameters used for making a bootp request
29  *
30  * @details
31  *    The bootp request parameters are created from these fields
32  */
33 typedef struct iblBootp_s
34 {
35     uint8   hwAddress[6]; /**< The hardware (mac) address of this device. If set to 0
36                                the ibl will values from e-fuse */
37     
38     uint8   ipDest[4];    /**< The IP address of this device. This is typically set
39                                to IP broadcast */
40     
41 } iblBootp_t;
44 /**
45  * @brief
46  *   This structure contains information used for tftp boot. 
47  *
48  * @details These fields are typically filled in by the bootp packet, but 
49  *          can be provided if bootp will not be used.
50  */
51 typedef struct iblEthBootInfo_s
52 {
53     uint8   ipAddr[4];      /**< The IP address of this device */
54     uint8   serverIp[4];    /**< The IP address of the tftp server */
55     uint8   gatewayIp[4];   /**< The IP address of the gateway */
56     uint8   netmask[4];     /**< The IP netmask */
57     uint8   hwAddress[6];   /**< The hardware (mac) address of this device */
58     char8   fileName[128];  /**< The file name to load */
60 } iblEthBootInfo_t;
61     
62     
63 /**
64  * @def ibl_ETH_PORT_FROM_RBL
65  */
66 #define ibl_ETH_PORT_FROM_RBL   -1  /**< The ethernet port used is the same one used 
67                                          during the ROM boot load process. */
70 /**
71  * @defgroup iblBootFormats
72  *
73  * @ingroup iblBootFormats
74  * @{
75  */ 
76 #define ibl_BOOT_FORMAT_AUTO    0   /**< Auto determine the boot format from the data */
77 #define ibl_BOOT_FORMAT_NAME    1   /**< Determines the boot format based on file name (bootp/tftp only) */
78 #define ibl_BOOT_FORMAT_BIS     2   /**< Boot TI AIS format */
79 #define ibl_BOOT_FORMAT_COFF    3   /**< Boot a COFF file */
80 #define ibl_BOOT_FORMAT_ELF     4   /**< Boot an ELF file */
81 #define ibl_BOOT_FORMAT_BBLOB   5   /**< Boot a binary blob */
82 #define ibl_BOOT_FORMAT_BTBL    6   /**< Boot a TI boot table file */
84 /* @} */
85  
86 /**
87  * @defgroup iblPeriphPriority  Defines the boot sequence
88  *
89  * @ingroup iblPeriphPriority
90  * @{
91  *    @def  ibl_LOWEST_PRIORITY
92  */
93 #define ibl_LOWEST_PRIORITY     10  /**< The lowest priority assignable to a peripheral for boot */
95 /**
96  *    @def  ibl_HIGHEST_PRIORITY
97  */
98 #define ibl_HIGHEST_PRIORITY     1  /**< The highest priority assignable to a peripheral for boot */
100 /**
101  *    @def  ibl_DEVICE_NOBOOT
102  */
103 #define ibl_DEVICE_NOBOOT       20  /**< Indicates that the device is not to be used for boot */
105 /* @} */  
108 /**
109  *  @brief
110  *      Emif controller 3.1 configuration
111  *
112  *  @details
113  *      The paramters are directly placed into the emif controller
114  */
115 typedef struct iblEmif3p1_s
117     uint32 sdcfg;           /**< SD configuration register */
118     uint32 sdrfc;           /**< Refresh timing register   */
119     uint32 sdtim1;          /**< DDR timing register 1 */
120     uint32 sdtim2;          /**< DDR timing register 2 */
121     uint32 dmcctl;          /**< CAS match timing */
122     
123 } iblEmif3p1_t;
126 /**
127  *  @brief
128  *      Emif controller 4.0 configuration
129  *
130  *  @details
131  *      The parameters are placed directly into the emif controller
132  */
133 typedef struct iblEmif4p0_s
135     uint32 dummy;           /**< placeholder */
136    
137 } iblEmif4p0_t;
139 /**
140  * @brief
141  *    This structure is used to configure the DDR interface
142  *
143  * @details
144  *    The DDR configuration parameters are setup
145  *
146  */
147 typedef struct idblDdr_s
149     bool configDdr;                  /**<  Set to non-zero to enable EMIF configuration */
150     
151     union  {
152     
153         iblEmif3p1_t  emif3p1;       /**<  Configuration of devices with emif controller version 3.1 */
154         iblEmif4p0_t  emif4p0;       /**<  Configuration of devices with emif controller version 4.0 */
155     } uEmif;
157 } iblDdr_t;
159 /**
160  *  @brief
161  *      This structure is used to identify binary blob load parameters.
162  *
163  *  @details
164  *      Since binary blob is formatless the start address, size and branch to address
165  *      can be specified. In the case of network boot, boot will terminate when no
166  *      more data is received (or timed out), even if the size is not reached.
167  */
168 typedef struct iblBinBlob_s
170     uint32   startAddress;          /**< Where the loaded data is placed */
171     uint32   sizeBytes;             /**< How much data to load */
172     uint32   branchAddress;         /**< Where to branch to when the load is complete */
174 } iblBinBlob_t;
176 /**
177  * @brief
178  *   This structure is used to control the operation of the ibl ethernet boot.
179  *
180  * @details
181  *   The ethernet port and bootp request are controlled through this structure.
182  */
183 typedef struct iblEth_s
185     uint32   ethPriority;       /**< The ethernet boot priority. @ref iblPeriphPriority */
186     int32    port;              /**< The ethernet port to use, or @ref ibl_ETH_PORT_FROM_RBL */
187     bool     doBootp;           /**< If true a bootp request is generated. If false the @ref iblEthBootInfo_t
188                                      table must be populated before the ibl begins execution */
189     bool     useBootpServerIp;  /**< If TRUE then the server IP received from the bootp server
190                                      is used, if FALSE the one in the ethInfo field is used */
191     bool     useBootpFileName;  /**< If TRUE then the file name received from the bootp server
192                                      is used, if FALSE the one in the ethInfo field is used */
193     int32    bootFormat;        /**< The format of the boot data file. @ref iblBootFormats */                            
194     
195     iblBinBlob_t blob;          /**< Used only if the format is ibl_BOOT_FORMAT_BBLOB */
196     
197     iblEthBootInfo_t  ethInfo;  /**< Low level ethernet information */
198     
199 } iblEth_t;
202 /**
203  *  @brief
204  *      This structure is used to control the operation of the ibl sgmii ports
205  *
206  *  @details
207  *      The physical register configuration is provided
208  */
209 typedef struct iblSgmii_s
211     uint32  adviseAbility;      /**< The advise ability register */
212     uint32  control;            /**< The control register        */
213     uint32  txConfig;           /**< Serdes Tx config            */
214     uint32  rxConfig;           /**< Serdes Rx config            */
215     uint32  auxConfig;          /**< Serdes Aux config           */
216   
217 } iblSgmii_t;
220 /**
221  *  @def ibl_N_ETH_PORTS
222  */
223 #define ibl_N_ETH_PORTS     2  /**< The number of ethernet port configurations available */
225 /**
226  *  @def ibl_N_MDIO_CFGS
227  */
228 #define ibl_N_MDIO_CFGS     16  /**< The maximum number of mdio configurations */
229  
231 /**
232  * @brief
233  *      This structure is used to configure phys through the mdio interface
234  *
235  * @details
236  *      Defines optional configuration through MDIO.
237  *
238  *      The mdio transaction values are mapped as follows:
239  *
240  *      /-------------------------------------------------------------\
241  *      |  31  |  30   | 29  26 | 25      21 | 20      16 | 15       0|
242  *      | rsvd | write |  rsvd  |  register  |  phy addr  |     data  |
243  *      \-------------------------------------------------------------/
244  */
245 typedef struct iblMdio_s
247     int16  nMdioOps;         /**< The number of mdio writes to perform  */
248     uint16 mdioClkDiv;       /**< The divide down of the mac clock which drives the mdio */
249     
250     uint32 interDelay;       /**< The number of cpu cycles to wait between mdio writes */
251     
252     uint32 mdio[ibl_N_MDIO_CFGS];   /* The MDIO transactions */
254 } iblMdio_t;
257 /** 
258  *  @brief
259  *      This structure defines the physical parameters of the NAND device
260  */
261 typedef struct nandDevInfo_s
263     uint32  busWidthBits;       /**< 8 or 16 bit bus width */
264     uint32  pageSizeBytes;      /**< The size of each page */
265     uint32  pageEccBytes;       /**< Number of ecc bytes in each page */
266     uint32  pagesPerBlock;      /**< The number of pages in each block */
267     uint32  totalBlocks;        /**< The total number of blocks in a device */
268     
269     uint32  addressBytes;       /**< Number of bytes in the address */
270     bool    lsbFirst;           /**< Set to true if the LSB is output first, otherwise msb is first */
271     uint32  blockOffset;        /**< Address bits which specify the block number */
272     uint32  pageOffset;         /**< Address bits which specify the page number */
273     uint32  columnOffset;       /**< Address bits which specify the column number */
274     
275     uint8   resetCommand;       /**< The command to reset the flash */
276     uint8   readCommandPre;     /**< The read command sent before the address */
277     uint8   readCommandPost;    /**< The read command sent after the address */
278     bool    postCommand;        /**< If TRUE the post command is sent */
279     
280 } nandDevInfo_t;
281     
282     
283 /**
284  *  @brief
285  *      This structure is used to control the operation of the NAND boot
286  *
287  */
288 typedef struct iblNand_s
291     uint32   nandPriority;      /**< The nand boot priority. @ref iblPeriphPriority */
292     int32    bootFormat;        /**< The format of the boot data file. @ref iblBootFormats */                            
293     iblBinBlob_t blob;          /**< Used only if the format is ibl_BOOT_FORMAT_BBLOB */
294     
295     
296     nandDevInfo_t nandInfo;     /** Low level device info */
298 } iblNand_t;
299     
300     
301 /**
302  *  @brief
303  *      This structure is used to control the programming of the device PLL
304  *
305  *  @details
306  *      The system PLLs are optionally configured
307  */
308 typedef struct iblPll_s  {
310     bool    doEnable;       /**< If true the PLL is configured */
311     
312     Uint32  prediv;         /**< The pll pre-divisor */
313     Uint32  mult;           /**< The pll multiplier */
314     Uint32  postdiv;        /**< The pll post divider */
315     
316     Uint32  pllOutFreqMhz;  /**<  The resulting output frequency, required for timer setup */ 
317     
318 } iblPll_t;
321 /** 
322  *  @defgroup iblPllNum
323  * 
324  *  @ingroup iblPllNum
325  *  @{
326  * 
327  *  @def ibl_MAIN_PLL
328  */
329 #define ibl_MAIN_PLL    0  /**< The main cpu pll */
331 /**
332  * @def ibl_DDR_PLL
333  */
334 #define ibl_DDR_PLL     1  /**< The ddr pll */
336 /**
337  * @def ibl_NET_PLL
338  */
339 #define ibl_NET_PLL     2  /**< The network pll */
341 /**
342  * @def the number of PLL configuration entries in the table
343  */
344 #define ibl_N_PLL_CFGS  (ibl_NET_PLL + 1)
346 /* @} */
347     
351 /**
352  * @def ibl_MAGIC_VALUE
353  */
354 #define ibl_MAGIC_VALUE  0xCEC11EBB  /**< Indicates that the configuration table is valid */
355     
356 /**
357  *  @brief
358  *    The main configuration/control structure for the ibl
359  *
360  *  @details
361  *    The operation of the ibl is configured/controlled based on the values in this structure. 
362  *    This structure resides at a fixed location in the memory map. It can be changed during
363  *    the boot operation itself by loading new values into it, but these changes must occur
364  *    as part of the boot process itself (not through an asynchronous write through a master
365  *    peripheral).
366  *
367  *    Each boot mode is assigned a priority, with lower values indicating a higher 
368  *    priority. The lowest valid priority is @ref ibl_LOWEST_BOOT_PRIORITY, and the value
369  *    @ref ibl_DEVICE_NOBOOT indicates no boot will be attempted on that peripheral. 
370  */
371 typedef struct ibl_s
373     uint32   iblMagic;                       /**< @ref ibl_MAGIC_VALUE */
374     
375     iblPll_t  pllConfig[ibl_N_PLL_CFGS];     /**< PLL Configuration. @ref iblPll_t */
376     
377     iblDdr_t  ddrConfig;                     /**< DDR configuration @ref iblDdr_t  */
378     
379     iblEth_t  ethConfig[ibl_N_ETH_PORTS];    /**< Ethernet boot configuration. @ref iblEth_t */
380     
381     iblSgmii_t sgmiiConfig[ibl_N_ETH_PORTS]; /**< SGMII boot configuration. @ref iblSgmii_t */
382     
383     iblMdio_t mdioConfig;                    /**< MDIO configuration. @ref iblMdio_t */
384     
385     iblNand_t nandConfig;                    /**< NAND configuration @ref iblNand_t */
386     
387     uint16    chkSum;                        /**< Ones complement checksum over the whole config structure */
388     
389     
390 /*    iblI2c_t  i2cConfig;  */
391 /*    iblSpi_t  spiConfig;  */
392     
393      
394 } ibl_t;
397 extern ibl_t ibl;
401 /**
402  * @defgroup iblActivePeriph
403  *
404  * @ingroup iblActivePeriph
405  * @{
406  *    @def  ibl_ACTIVE_PERIPH_ETH
407  */
408 #define ibl_ACTIVE_PERIPH_ETH     100     /**< An ethernet boot in progress */
410 /**
411  *  @def ibl_ACTIVE_PERIPH_NAND
412  */
413 #define ibl_ACTIVE_PERIPH_NAND    101     /**< A nand boot in progress */
415 /**
416  *  @def ibl_ACTIVE_PERIPH_I2C
417  */
418 #define ibl_ACTIVE_PERIPH_I2C     102     /**< An i2c boot in progress */
420 /**
421  *  @def ibl_ACTIVE_PERIPH_SPI
422  */
423 #define ibl_ACTIVE_PERIPH_SPI     103     /**< An SPI boot in progress */
425 /* @} */
428 /**
429  *  @defgroup iblFailCode
430  *
431  * @ingroup iblFailCode
432  * @{
433  *      @def ibl_FAIL_CODE_INVALID_I2C_ADDRESS
434  */
435 #define ibl_FAIL_CODE_INVALID_I2C_ADDRESS  700      /**< Invalid i2c eeprom address encountered */
436  
437 /**
438  *  @def ibl_FAIL_CODE_BTBL_FAIL
439  */
440 #define ibl_FAIL_CODE_BTBL_FAIL             701     /**< Boot table processing function error */
442  
443  /* @} */
446 /**
447  * @brief
448  *   Provide status on the boot operation
449  *
450  * @details
451  *  Run time status of the IBL is provided to aid in debugging
452  *
453  */
454 typedef struct iblStatus_s
456     uint32 iblMagic;        /**<  The @ref ibl_MAGIC_VALUE is placed here to indicate the boot has begun */
457     
458     uint32 iblFail;         /**<  If non-zero the IBL has encountered a fatal error */
459     
460     uint32 i2cRetries;      /**<  Count of I2C read retries */
461     uint32 magicRetries;    /**<  Count of I2C re-reads because the magic number was incorrect */ 
462     uint32 mapSizeFail;     /**<  Number of times an invalid map table size was read from the i2c */
463     uint32 mapRetries;      /**<  Number of times the checksum failed on the read of the i2c map */
464     uint32 i2cDataRetries;  /**<  Number of retries while reading block data from the i2c */
465     
466     int32  tableLoadFail;   /**<  If non-zero then the load of the parameter table from i2c failed */
467     
468     int32  heartBeat;       /**<  An increasing value as long as the boot code is running */
469     int32  noMagic;         /**<  A non-zero value here indicates that @ref ibl_MAGIC_VALUE was not found
470                                   in the @ref ibl_t magic field, and default values were loaded. */
471     int32  activePeriph;    /**<  Describes the active boot peripheral @ref iblActivePeriph */
472     int32  activeFormat;    /**<  Describes the format being decoded */
473     
474     int32  autoDetectFailCnt;       /**<  Counts the number of times an auto detect of the data format failed */
475     int32  nameDetectFailCnt;       /**<  Counts the number of times an name detect of the data format failed */
476     
477     int32 invalidDataFormatSpec;    /**<  Counts the number of times the main boot found an invalid boot format request */
478     
479     uint32 exitAddress;             /**<  If non-zero the IBL exited and branched to this address */
480     
481     iblEthBootInfo_t ethParams;     /**<  Last ethernet boot attemp parameters */
482     
483 } iblStatus_t;                               
484                                
485 extern iblStatus_t iblStatus;                               
488 /** 
489  *  @brief
490  *      The i2c map structure
491  *
492  *  @details 
493  *      The i2c eeprom contains a structure which identifies the location of the big and little
494  *      endian ibl images on the eeprom.
495  */
496 typedef struct iblI2cMap_s 
498     uint16  length;         /**<  Size of the structure in bytes */
499     uint16  chkSum;         /**<  Value which makes the ones complement checksum over the block equal to 0 or -0 */
500     uint32  addrLe;         /**<  Base address of the boot tables for the little endian image */
501     uint32  addrBe;         /**<  Base address of the boot tables for the big endian image */
503 } iblI2cMap_t;
512 #endif /* IBL_H */