1 /***********************license start***************
2 * Copyright (c) 2003-2008 Cavium Networks (support@cavium.com). All rights
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above
14 * copyright notice, this list of conditions and the following
15 * disclaimer in the documentation and/or other materials provided
16 * with the distribution.
18 * * Neither the name of Cavium Networks nor the names of
19 * its contributors may be used to endorse or promote products
20 * derived from this software without specific prior written
23 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
24 * AND WITH ALL FAULTS AND CAVIUM NETWORKS MAKES NO PROMISES, REPRESENTATIONS
25 * OR WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH
26 * RESPECT TO THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY
27 * REPRESENTATION OR DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT
28 * DEFECTS, AND CAVIUM SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES
29 * OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR
30 * PURPOSE, LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET
31 * POSSESSION OR CORRESPONDENCE TO DESCRIPTION. THE ENTIRE RISK ARISING OUT
32 * OF USE OR PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
35 * For any questions regarding licensing please contact marketing@caviumnetworks.com
37 ***********************license end**************************************/
47 * This header defines the CVMX interface to the NAND flash controller. The
48 * basic operations common to all NAND devices are supported by this API, but
49 * many more advanced functions are not support. The low level hardware supports
50 * all types of transactions, but this API only implements the must commonly
51 * used operations. This API performs no locking, so it is the responsibility of
52 * the caller to make sure only one thread of execution is accessing the NAND
53 * controller at a time. Most applications should not use this API directly but
54 * instead use a flash logical layer supplied through a secondary system. For
55 * example, the Linux MTD layer provides a driver for running JFFS2 on top of
58 * <h2>Selecting the NAND Chip</h2>
60 * Octeon's NAND controller assumes a single NAND chip is connected to a boot
61 * bus chip select. Throughout this API, NAND chips are referred to by the chip
62 * select they are connected to (0-7). Chip select 0 will only be a NAND chip
63 * when you are booting from NAND flash.
65 * <h2>NAND Addressing</h2>
67 * Various functions in cvmx-nand use addresses to index into NAND flash. All
68 * functions us a uniform address translation scheme to map the passed address
69 * into a NAND block, page, and column. In NAND flash a page represents the
70 * basic unit of reads and writes. Each page contains a power of two number of
71 * bytes and some number of extra out of band (OOB) bytes. A fixed number of
72 * pages fit into each NAND block. Here is the mapping of bits in the cvmx-nand
73 * address to the NAND hardware:
75 * 63 56 48 40 32 24 16 8 0
76 * +-------+-------+-------+-------+-------+-------+-------+------+
77 * | 64 bit cvmx-nand nand_address|
78 * +------------------------------------------------+----+--------+
79 * | block |page| column |
80 * +-------+-------+-------+-------+-------+--------+----+--------+
81 * 63 56 48 40 32 24 16 8 0
83 * Basically the block, page, and column addresses are packet together. Before
84 * being sent out the NAND pins for addressing the column is padded out to an
85 * even number of bytes. This means that column address are 2 bytes, or 2
86 * address cycles, for page sizes between 512 and 65536 bytes. Page sizes
87 * between 128KB and 16MB would use 3 column address cycles. NAND device
88 * normally either have 32 or 64 pages per block, needing either 5 or 6 address
89 * bits respectively. This means you have 10 bits for block address using 4
90 * address cycles, or 18 for 5 address cycles. Using the cvmx-nand addressing
91 * scheme, it is not possible to directly index the OOB data. Instead you can
92 * access it by reading or writing more data than the normal page size would
93 * allow. Logically the OOB data is appended onto the the page data. For
94 * example, this means that a read of 65 bytes from a column address of 0x7ff
95 * would yield byte 2047 of the page and then 64 bytes of OOB data.
97 * <hr>$Revision: 35726 $<hr>
100 #ifndef __CVMX_NAND_H__
101 #define __CVMX_NAND_H__
108 /* Block size for boot ECC */
109 #define CVMX_NAND_BOOT_ECC_BLOCK_SIZE (256)
110 /* ECC bytes for each block */
111 #define CVMX_NAND_BOOT_ECC_ECC_SIZE (8)
114 * Flags to be passed to the initialize function
118 CVMX_NAND_INITIALIZE_FLAGS_16BIT = 1<<0,
119 CVMX_NAND_INITIALIZE_FLAGS_DONT_PROBE = 1<<1,
120 CVMX_NAND_INITIALIZE_FLAGS_DEBUG = 1<<15,
121 } cvmx_nand_initialize_flags_t;
124 * Return codes from NAND functions
128 CVMX_NAND_SUCCESS = 0,
129 CVMX_NAND_NO_MEMORY = -1,
131 CVMX_NAND_INVALID_PARAM = -3,
132 CVMX_NAND_TIMEOUT = -4,
133 } cvmx_nand_status_t;
136 * NAND NOP command definition
140 uint64_t reserved_64_127 : 64;
141 uint64_t reserved_4_63 : 60;
143 } cvmx_nand_cmd_nop_t;
146 * NAND SET_TM_PAR command definition
150 uint64_t reserved_64_127 : 64;
151 uint64_t tim_par7 : 8;
152 uint64_t tim_par6 : 8;
153 uint64_t tim_par5 : 8;
154 uint64_t tim_par4 : 8;
155 uint64_t tim_par3 : 8;
156 uint64_t tim_par2 : 8;
157 uint64_t tim_par1 : 8;
158 uint64_t tim_mult : 4;
160 } cvmx_nand_cmd_set_tm_par_t;
163 * NAND WAIT command definition
167 uint64_t reserved_64_127 : 64;
168 uint64_t reserved_11_63 : 53;
170 uint64_t reserved_5_7 : 3;
173 } cvmx_nand_cmd_wait_t;
176 * NAND CHIP_EN command definition
180 uint64_t reserved_64_127 : 64;
181 uint64_t reserved_10_63 : 54;
186 } cvmx_nand_cmd_chip_en_t;
189 * NAND CHIP_DIS command definition
193 uint64_t reserved_64_127 : 64;
194 uint64_t reserved_4_63 : 60;
196 } cvmx_nand_cmd_chip_dis_t;
199 * NAND CLE command definition
203 uint64_t reserved_64_127 : 64;
204 uint64_t reserved_25_63 : 39;
208 uint64_t cmd_data : 8;
209 uint64_t reserved_4_7 : 4;
211 } cvmx_nand_cmd_cle_t;
214 * NAND ALE command definition
218 uint64_t reserved_96_127 : 32;
219 uint64_t adr_bytes_h : 32;
220 uint64_t adr_bytes_l : 32;
221 uint64_t reserved_28_31 : 4;
226 uint64_t reserved_12_15 : 4;
227 uint64_t adr_byte_num : 4;
228 uint64_t reserved_4_7 : 4;
230 } cvmx_nand_cmd_ale_t;
233 * NAND WR command definition
237 uint64_t reserved_64_127 : 64;
238 uint64_t reserved_31_63 : 34;
241 uint64_t reserved_20_24 : 4;
242 uint64_t data_bytes : 16;
244 } cvmx_nand_cmd_wr_t;
247 * NAND RD command definition
251 uint64_t reserved_64_127 : 64;
252 uint64_t reserved_32_63 : 32;
257 uint64_t data_bytes : 16;
259 } cvmx_nand_cmd_rd_t;
262 * NAND RD_EDO command definition
266 uint64_t reserved_64_127 : 64;
267 uint64_t reserved_32_63 : 32;
272 uint64_t data_bytes : 16;
274 } cvmx_nand_cmd_rd_edo_t;
277 * NAND WAIT_STATUS command definition
285 uint64_t comp_byte : 8;
286 uint64_t and_mask : 8;
288 uint64_t reserved_28_95 : 64;
294 uint64_t reserved_4_7 : 4;
296 } cvmx_nand_cmd_wait_status_t;
299 * NAND WAIT_STATUS_ALE command definition
307 uint64_t comp_byte : 8;
308 uint64_t and_mask : 8;
310 uint64_t adr_bytes : 32;
311 uint64_t reserved_60_63 : 4;
316 uint64_t reserved_44_47 : 4;
317 uint64_t adr_byte_num : 4;
319 uint64_t reserved_25_31 : 7;
324 uint64_t reserved_4_7 : 4;
326 } cvmx_nand_cmd_wait_status_ale_t;
329 * NAND BUS_ACQ command definition
333 uint64_t reserved_64_127 : 64;
334 uint64_t reserved_8_63 : 56;
336 uint64_t fifteen : 4;
337 } cvmx_nand_cmd_bus_acq_t;
340 * NAND BUS_REL command definition
344 uint64_t reserved_64_127 : 64;
345 uint64_t reserved_8_63 : 56;
347 uint64_t fifteen : 4;
348 } cvmx_nand_cmd_bus_rel_t;
351 * NAND command union of all possible commands
356 cvmx_nand_cmd_nop_t nop;
357 cvmx_nand_cmd_set_tm_par_t set_tm_par;
358 cvmx_nand_cmd_wait_t wait;
359 cvmx_nand_cmd_chip_en_t chip_en;
360 cvmx_nand_cmd_chip_dis_t chip_dis;
361 cvmx_nand_cmd_cle_t cle;
362 cvmx_nand_cmd_ale_t ale;
363 cvmx_nand_cmd_rd_t rd;
364 cvmx_nand_cmd_rd_edo_t rd_edo;
365 cvmx_nand_cmd_wr_t wr;
366 cvmx_nand_cmd_wait_status_t wait_status;
367 cvmx_nand_cmd_wait_status_ale_t wait_status_ale;
368 cvmx_nand_cmd_bus_acq_t bus_acq;
369 cvmx_nand_cmd_bus_rel_t bus_rel;
372 uint64_t reserved_64_127: 64;
373 uint64_t reserved_4_63 : 60;
374 uint64_t op_code : 4;
379 typedef struct __attribute__ ((packed))
381 char onfi[4]; /**< Bytes 0-3: The ASCII characters 'O', 'N', 'F', 'I' */
382 uint16_t revision_number; /**< Bytes 4-5: ONFI revision number
384 - 1 1 = supports ONFI version 1.0
386 uint16_t features; /**< Bytes 6-7: Features supported
388 - 4 1 = supports odd to even page Copyback
389 - 3 1 = supports interleaved operations
390 - 2 1 = supports non-sequential page programming
391 - 1 1 = supports multiple LUN operations
392 - 0 1 = supports 16-bit data bus width */
393 uint16_t optional_commands; /**< Bytes 8-9: Optional commands supported
395 - 5 1 = supports Read Unique ID
396 - 4 1 = supports Copyback
397 - 3 1 = supports Read Status Enhanced
398 - 2 1 = supports Get Features and Set Features
399 - 1 1 = supports Read Cache commands
400 - 0 1 = supports Page Cache Program command */
401 uint8_t reserved_10_31[22]; /**< Bytes 10-31: Reserved */
403 char manufacturer[12]; /**< Bytes 32-43: Device manufacturer (12 ASCII characters) */
404 char model[20]; /**< Bytes 40-63: Device model (20 ASCII characters) */
405 uint8_t jedec_id; /**< Byte 64: JEDEC manufacturer ID */
406 uint16_t date_code; /**< Byte 65-66: Date code */
407 uint8_t reserved_67_79[13]; /**< Bytes 67-79: Reserved */
409 uint32_t page_data_bytes; /**< Bytes 80-83: Number of data bytes per page */
410 uint16_t page_spare_bytes; /**< Bytes 84-85: Number of spare bytes per page */
411 uint32_t partial_page_data_bytes; /**< Bytes 86-89: Number of data bytes per partial page */
412 uint16_t partial_page_spare_bytes; /**< Bytes 90-91: Number of spare bytes per partial page */
413 uint32_t pages_per_block; /**< Bytes 92-95: Number of pages per block */
414 uint32_t blocks_per_lun; /**< Bytes 96-99: Number of blocks per logical unit (LUN) */
415 uint8_t number_lun; /**< Byte 100: Number of logical units (LUNs) */
416 uint8_t address_cycles; /**< Byte 101: Number of address cycles
417 - 4-7 Column address cycles
418 - 0-3 Row address cycles */
419 uint8_t bits_per_cell; /**< Byte 102: Number of bits per cell */
420 uint16_t bad_block_per_lun; /**< Bytes 103-104: Bad blocks maximum per LUN */
421 uint16_t block_endurance; /**< Bytes 105-106: Block endurance */
422 uint8_t good_blocks; /**< Byte 107: Guaranteed valid blocks at beginning of target */
423 uint16_t good_block_endurance; /**< Bytes 108-109: Block endurance for guaranteed valid blocks */
424 uint8_t programs_per_page; /**< Byte 110: Number of programs per page */
425 uint8_t partial_program_attrib; /**< Byte 111: Partial programming attributes
427 - 4 1 = partial page layout is partial page data followed by partial page spare
429 - 0 1 = partial page programming has constraints */
430 uint8_t bits_ecc; /**< Byte 112: Number of bits ECC correctability */
431 uint8_t interleaved_address_bits; /**< Byte 113: Number of interleaved address bits
433 - 0-3 Number of interleaved address bits */
434 uint8_t interleaved_attrib; /**< Byte 114: Interleaved operation attributes
436 - 3 Address restrictions for program cache
437 - 2 1 = program cache supported
438 - 1 1 = no block address restrictions
439 - 0 Overlapped / concurrent interleaving support */
440 uint8_t reserved_115_127[13]; /**< Bytes 115-127: Reserved (0) */
442 uint8_t pin_capacitance; /**< Byte 128: I/O pin capacitance */
443 uint16_t timing_mode; /**< Byte 129-130: Timing mode support
445 - 5 1 = supports timing mode 5
446 - 4 1 = supports timing mode 4
447 - 3 1 = supports timing mode 3
448 - 2 1 = supports timing mode 2
449 - 1 1 = supports timing mode 1
450 - 0 1 = supports timing mode 0, shall be 1 */
451 uint16_t cache_timing_mode; /**< Byte 131-132: Program cache timing mode support
453 - 5 1 = supports timing mode 5
454 - 4 1 = supports timing mode 4
455 - 3 1 = supports timing mode 3
456 - 2 1 = supports timing mode 2
457 - 1 1 = supports timing mode 1
458 - 0 1 = supports timing mode 0 */
459 uint16_t t_prog; /**< Byte 133-134: Maximum page program time (us) */
460 uint16_t t_bers; /**< Byte 135-136: Maximum block erase time (us) */
461 uint16_t t_r; /**< Byte 137-148: Maximum page read time (us) */
462 uint16_t t_ccs; /**< Byte 139-140: Minimum change column setup time (ns) */
463 uint8_t reserved_141_163[23]; /**< Byte 141-163: Reserved (0) */
465 uint16_t vendor_revision; /**< Byte 164-165: Vendor specific Revision number */
466 uint8_t vendor_specific[88]; /**< Byte 166-253: Vendor specific */
467 uint16_t crc; /**< Byte 254-255: Integrity CRC */
468 } cvmx_nand_onfi_param_page_t;
472 * Called to initialize the NAND controller for use. Note that
473 * you must be running out of L2 or memory and not NAND before
474 * calling this function.
476 * @param flags Optional initialization flags
477 * @param active_chips
478 * Each bit in this parameter represents a chip select that might
479 * contain NAND flash. Any chip select present in this bitmask may
480 * be connected to NAND. It is normally safe to pass 0xff here and
481 * let the API probe all 8 chip selects.
483 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
485 extern cvmx_nand_status_t cvmx_nand_initialize(cvmx_nand_initialize_flags_t flags, int active_chips);
489 * Call to shutdown the NAND controller after all transactions
490 * are done. In most setups this will never be called.
492 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
494 extern cvmx_nand_status_t cvmx_nand_shutdown(void);
498 * Returns a bitmask representing the chip selects that are
499 * connected to NAND chips. This can be called after the
500 * initialize to determine the actual number of NAND chips
501 * found. Each bit in the response coresponds to a chip select.
503 * @return Zero if no NAND chips were found. Otherwise a bit is set for
504 * each chip select (1<<chip).
506 extern int cvmx_nand_get_active_chips(void);
510 * Override the timing parameters for a NAND chip
512 * @param chip Chip select to override
520 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
522 extern cvmx_nand_status_t cvmx_nand_set_timing(int chip, int tim_mult, int tim_par[7], int clen[4], int alen[4], int rdn[4], int wrn[2]);
526 * Submit a command to the NAND command queue. Generally this
527 * will not be used directly. Instead most programs will use the other
528 * higher level NAND functions.
530 * @param cmd Command to submit
532 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
534 extern cvmx_nand_status_t cvmx_nand_submit(cvmx_nand_cmd_t cmd);
537 * Read a page from NAND. If the buffer has room, the out of band
538 * data will be included.
540 * @param chip Chip select for NAND flash
541 * @param nand_address
542 * Location in NAND to read. See description in file comment
543 * @param buffer_address
544 * Physical address to store the result at
545 * @param buffer_length
546 * Number of bytes to read
548 * @return Bytes read on success, a negative cvmx_nand_status_t error code on failure
550 extern int cvmx_nand_page_read(int chip, uint64_t nand_address, uint64_t buffer_address, int buffer_length);
553 * Write a page to NAND. The buffer must contain the entire page
554 * including the out of band data.
556 * @param chip Chip select for NAND flash
557 * @param nand_address
558 * Location in NAND to write. See description in file comment
559 * @param buffer_address
560 * Physical address to read the data from
562 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
564 extern cvmx_nand_status_t cvmx_nand_page_write(int chip, uint64_t nand_address, uint64_t buffer_address);
567 * Erase a NAND block. A single block contains multiple pages.
569 * @param chip Chip select for NAND flash
570 * @param nand_address
571 * Location in NAND to erase. See description in file comment
573 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
575 extern cvmx_nand_status_t cvmx_nand_block_erase(int chip, uint64_t nand_address);
578 * Read the NAND ID information
580 * @param chip Chip select for NAND flash
581 * @param nand_address
582 * NAND address to read ID from. Usually this is either 0x0 or 0x20.
583 * @param buffer_address
584 * Physical address to store data in
585 * @param buffer_length
586 * Length of the buffer. Usually this is 4 bytes
588 * @return Bytes read on success, a negative cvmx_nand_status_t error code on failure
590 extern int cvmx_nand_read_id(int chip, uint64_t nand_address, uint64_t buffer_address, int buffer_length);
593 * Read the NAND parameter page
595 * @param chip Chip select for NAND flash
596 * @param buffer_address
597 * Physical address to store data in
598 * @param buffer_length
599 * Length of the buffer. Usually this is 4 bytes
601 * @return Bytes read on success, a negative cvmx_nand_status_t error code on failure
603 extern int cvmx_nand_read_param_page(int chip, uint64_t buffer_address, int buffer_length);
606 * Get the status of the NAND flash
608 * @param chip Chip select for NAND flash
610 * @return NAND status or a negative cvmx_nand_status_t error code on failure
612 extern int cvmx_nand_get_status(int chip);
615 * Get the page size, excluding out of band data. This function
616 * will return zero for chip selects not connected to NAND.
618 * @param chip Chip select for NAND flash
620 * @return Page size in bytes or a negative cvmx_nand_status_t error code on failure
622 extern int cvmx_nand_get_page_size(int chip);
627 * @param chip Chip select for NAND flash
629 * @return OOB in bytes or a negative cvmx_nand_status_t error code on failure
631 extern int cvmx_nand_get_oob_size(int chip);
634 * Get the number of pages per NAND block
636 * @param chip Chip select for NAND flash
638 * @return Numboer of pages in each block or a negative cvmx_nand_status_t error code on failure
640 extern int cvmx_nand_get_pages_per_block(int chip);
643 * Get the number of blocks in the NAND flash
645 * @param chip Chip select for NAND flash
647 * @return Number of blocks or a negative cvmx_nand_status_t error code on failure
649 extern int cvmx_nand_get_blocks(int chip);
652 * Reset the NAND flash
654 * @param chip Chip select for NAND flash
656 * @return Zero on success, a negative cvmx_nand_status_t error code on failure
658 extern cvmx_nand_status_t cvmx_nand_reset(int chip);
661 * This function computes the Octeon specific ECC data used by the NAND boot
664 * @param block pointer to 256 bytes of data
665 * @param eccp pointer to where 8 bytes of ECC data will be stored
667 extern void cvmx_nand_compute_boot_ecc(unsigned char *block, unsigned char *eccp);
670 extern int cvmx_nand_correct_boot_ecc(uint8_t *block);
675 #endif /* __CVMX_NAND_H__ */