Software APIs
dif_flash_ctrl.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_FLASH_CTRL_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_FLASH_CTRL_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/top_earlgrey/ip_autogen/flash_ctrl/doc/">Flash
11 * Controller</a> Device Interface Functions
12 */
13
15#include "sw/device/lib/base/multibits.h"
16
17#include "sw/device/lib/dif/autogen/dif_flash_ctrl_autogen.h"
18
19#ifdef __cplusplus
20extern "C" {
21#endif // __cplusplus
22
23/**
24 * Carries state for a flash controller device.
25 *
26 * All members except the `dev` should be considered private and should not be
27 * accessed directly outside of the DIF implementation.
28 */
29typedef struct dif_flash_ctrl_state {
30 /**
31 * Contains autogenerated device information, like the base address for
32 * registers in the flash controller device.
33 */
35
36 /* Private members below. */
37
38 /** Number of words remaining for the current transaction. */
40 /** Whether a transaction is pending completion. */
43
44/**
45 * Initialize the DIF state for the flash controller.
46 *
47 * @param handle The flash controller DIF state to initialize.
48 * @param base_addr The base address for the flash controller.
49 * @return `kDifBadArg` if `handle` is null. `kDifOk` otherwise.
50 */
53 mmio_region_t base_addr);
54
55/**
56 * Initialize the DIF state for the flash controller.
57 *
58 * @param handle The flash controller DIF state to initialize.
59 * @param dt The flash controller dt.
60 * @return `kDifBadArg` if `handle` is null. `kDifOk` otherwise.
61 */
65
67 /** Number of banks under this flash controller. */
68 uint32_t num_banks;
69 /** Number of bytes per flash word. */
71 /** Number of bytes per flash page. */
73 /** Number of pages per bank in the data partition. */
74 uint32_t data_pages;
75 /** Number of pages per bank in the info partition, type 0. */
76 uint32_t info0_pages;
77 /** Number of pages per bank in the info partition, type 1. */
78 uint32_t info1_pages;
79 /** Number of pages per bank in the info partition, type 2. */
80 uint32_t info2_pages;
81} dif_flash_ctrl_device_info_t;
82
83// TODO: Associate the data with a base address or acknowledge that there
84// should only ever be one flash controller in the system.
85/**
86 * Get information on the flash controller sizes.
87 *
88 * @return A `dif_flash_ctrl_device_info_t` representing the feature sizes for
89 * various components of the flash.
90 */
92dif_flash_ctrl_device_info_t dif_flash_ctrl_get_device_info(void);
93
94/**
95 * Set whether the flash is enabled.
96 *
97 * Generally, this is used to disable flash functionality in case of an
98 * emergency. Flash functionality is ordinarily enabled.
99 *
100 * @param handle The flash controller to operate on.
101 * @param enable Enable/disable flash functionality.
102 * @return `kDifBadArg` if `handle` is null. `kDifOk` otherwise.
103 */
106 dif_toggle_t enable);
107
108/**
109 * Get whether flash functionality is enabled.
110 *
111 * @param handle The flash controller to operate on.
112 * @param enabled_out Out parameter, where to store whether flash is enabled.
113 * @return `kDifBadArg` if `handle` or `enabled_out` are null and `kDifOk`
114 * otherwise.
115 */
118 const dif_flash_ctrl_state_t *handle, dif_toggle_t *enabled_out);
119
120/**
121 * Set whether execution / fetch access is enabled.
122 *
123 * @param handle The flash controller to operate on.
124 * @param enable Enable/disable execution / fetch access.
125 * @return `kDifBadArg` if `handle` or `enabled_out` are null and `kDifOk`
126 * otherwise.
127 */
130 dif_toggle_t enable);
131
132/**
133 * Get whether execution / fetch access is enabled.
134 *
135 * @param handle The flash controller to operate on.
136 * @param enabled_out Out parameter, whether execution / fetch access is
137 * allowed.
138 * @return `kDifBadArg` if `handle` or `enabled_out` are null and `kDifOk`
139 * otherwise.
140 */
143 const dif_flash_ctrl_state_t *handle, dif_toggle_t *enabled_out);
144
145/**
146 * Begins the flash controller's initialization sequence. The flash controller
147 * will read out the root seeds before allowing other usage of the controller.
148 * This operation will only be performed once, and controller initialization
149 * cannot be requested again until after a reset.
150 *
151 * @param handle The flash controller to operate on.
152 * @return `kDifBadArg` if `handle` is null, `kDifError` if initialization has
153 * already been started, and `kDifOk` otherwise.
154 */
157 dif_flash_ctrl_state_t *handle);
158
159/**
160 * Status bits that can be queried.
161 */
162typedef struct dif_flash_ctrl_status {
163 /**
164 * Flash read FIFO full, software must consume data.
165 */
167 /**
168 * Flash read FIFO empty.
169 */
171 /**
172 * Flash program FIFO full.
173 */
175 /**
176 * Flash program FIFO empty, software must provide data.
177 */
179 /**
180 * Flash controller undergoing init.
181 */
183 /**
184 * Flash controller initialized.
185 */
188
189/**
190 * Query the status registers on the flash controller.
191 *
192 * This function checks the various status bits as described in
193 * `dif_flash_ctrl_status_t`.
194 *
195 * @param handle flash controller device to check the status bits for.
196 * @param status_out Out parameter. The current status of the flash controller.
197 * @return `kDifBadArg` if `handle` or `status_out` is null, `kDifOk` otherwise.
198 */
201 dif_flash_ctrl_status_t *status_out);
202
203/**
204 * Represents programming capabilities of the flash controller. The meaning of
205 * the boolean values is context-sensitive. For the result of a query, they
206 * represent which types are allowed. As an argument to a function that disables
207 * capabilities, a true value indicates that the function should disable that
208 * type.
209 */
211 /** Normal programming type. */
213 /** Repair programming type. */
216
217/**
218 * Query the allowed programming types.
219 *
220 * Note that this function is a check of a permission only. For checking whether
221 * the flash supports a given type, use `dif_flash_ctrl_get_phy_status()`.
222 * @sa dif_flash_ctrl_get_phy_status
223 *
224 * @param handle The flash controller to query.
225 * @param allowed_types_out Out parameter. Points to location where the allowed
226 * types should be written.
227 * @return `kDifBadArg` if `handle` or `allowed_types_out` are null. `kDifOk`
228 * otherwise.
229 */
232 const dif_flash_ctrl_state_t *handle,
233 dif_flash_ctrl_prog_capabilities_t *allowed_types_out);
234
235/**
236 * Disallow the indicated programming operations.
237 *
238 * Note that this is a one-way operation. Programming types that are disabled
239 * cannot be enabled again without a reset.
240 *
241 * @param handle The flash controller to operate on.
242 * @param types_to_disallow A programming type marked true indicates that the
243 * given type should be *disabled*.
244 * @return `kDifBadArg` if handle is null. `kDifOk` otherwise.
245 */
249 dif_flash_ctrl_prog_capabilities_t types_to_disable);
250
251/**
252 * Enum to represent the flash partition type (data or info).
253 */
255 kDifFlashCtrlPartitionTypeData = 0,
256 kDifFlashCtrlPartitionTypeInfo = 1
258
260 /** Read the specified number of words. */
262 /** Program the specified number of words (normal mode). */
264 /**
265 * Program the specified number of words in repair mode. Support for this
266 * mode depends on the underlying flash technology. See
267 * `dif_flash_ctrl_supports_repair_operation`.
268 */
270 /** Erase the specified page. */
272 /** Erase the specified bank. */
274} dif_flash_ctrl_operation_t;
275
277 dif_flash_ctrl_operation_t op;
278 /**
279 * The partition type for the transaction.
280 *
281 * Note: For bank erase operations, the data partition is *always* erased,
282 * even when `partition_type` is `kFlashCtrlPartitionTypeInfo`.
283 *
284 */
286 /**
287 * The index / ID of the info partition. Unused for data partitions, since
288 * there is only one in a given bank.
289 */
290 uint32_t partition_id;
291 /**
292 * Byte address (in the flash address space) to start the operation.
293 *
294 * For operations at a granularity of words, the flash controller will
295 * truncate to the closest, lower word aligned address. For example, if 0x13
296 * is supplied for a read, the controller will perform a read at address 0x10.
297 *
298 * Similarly, for page erase and bank erase operations, the flash controller
299 * will truncate to the closest lower page-aligned or bank-aligned address,
300 * respectively.
301 */
302 uint32_t byte_address;
303 /**
304 * Number of 32-bit words in the operation. Must be in the range [1,4096]
305 * (inclusive) for program or read operations. Unused for erase operations.
306 */
307 uint32_t word_count;
308} dif_flash_ctrl_transaction_t;
309
310/**
311 * Start a flash controller operation.
312 *
313 * Note that not all underlying flash memory supports the
314 * `kDifFlashCtrlOpProgramRepair` operation. When specifying this in the `op`,
315 * `dif_flash_ctrl_get_phy_status()` can first be used to ensure the operation
316 * is supported.
317 *
318 * @param handle The flash controller device to execute the transaction on.
319 * @param transaction The parameters that constitute the operation to start.
320 * @return `kDifBadArg` if `handle` is null or `transaction` contains an invalid
321 * or unsupported operation, `kDifUnavailable` if a flash transaction is in
322 * progress at the controller, `kDifIpFifoFull` if the FIFOs are not empty, and
323 * `kDifOk` otherwise.
324 */
327 dif_flash_ctrl_transaction_t transaction);
328
329/**
330 * Start a flash controller operation, with fewer safeguards. (unsafe version)
331 *
332 * Unlike `dif_flash_ctrl_start()`, this variant does not check whether the info
333 * partition id is valid, whether the word count is valid, or whether the FIFOs
334 * have been emptied. This function is intended to be used to trigger errors on
335 * purpose, for testing the hardware responses.
336 *
337 * Note that not all underlying flash memory supports the
338 * `kDifFlashCtrlOpProgramRepair` operation. When specifying this in the `op`,
339 * `dif_flash_ctrl_get_phy_status()` can first be used to ensure the operation
340 * is supported.
341 *
342 * @param handle The flash controller device to execute the transaction on.
343 * @param transaction The parameters that constitute the operation to start.
344 * @return `kDifBadArg` if `handle` is null, `kDifUnavailable` if a flash
345 * transaction is in progress, and `kDifOk` otherwise.
346 */
349 dif_flash_ctrl_state_t *handle, dif_flash_ctrl_transaction_t transaction);
350
351/**
352 * Suspend an ongoing erase transaction.
353 *
354 * If no erase transaction is ongoing, returns with no effect.
355 *
356 * @param handle flash controller device to operate on.
357 * @return `kDifBadArg` if `handle` is null. Otherwise, `kDifOk`.
358 */
361
362/**
363 * Query the controller for any erase suspension requests pending.
364 *
365 * @param handle The flash controller to query.
366 * @param request_pending_out Out parameter. The location to write whether an
367 * erase suspension request is pending.
368 * @return `kDifBadArg` if `handle` or `request_pending_out` are null. `kDifOk`
369 * otherwise.
370 */
373 dif_flash_ctrl_state_t *handle, bool *request_pending_out);
374
375/**
376 * Push data to the program FIFO. (unsafe version)
377 *
378 * This function is primarily for testing hardware error responses. If you are
379 * not specifically trying to force an error, consider
380 * `dif_flash_ctrl_prog_fifo_push()` instead. This function does not check if a
381 * program transaction has begun, nor if the number of words would exceed the
382 * size of the current transaction.
383 *
384 * Attempts to write the contents of `data` to the program FIFO without
385 * consideration for the current controller state.
386 *
387 * It is up to the caller to call `dif_flash_ctrl_end()` to ensure the
388 * flash controller completed this transaction successfully.
389 *
390 * @param handle flash controller device to push data to.
391 * @param word_count The number of words to write.
392 * @param data The data to write.
393 * @return `kDifBadArg` if `handle` or `data` are null. `kDifOk` otherwise.
394 */
397 dif_flash_ctrl_state_t *handle, uint32_t word_count, const uint32_t *data);
398
399/**
400 * Push data to the program FIFO.
401 *
402 * Attempts to write the contents of `data` to the program FIFO. It is required
403 * that a program transaction be started prior to calling this function, else
404 * the call will fail with `kDifError`.
405 *
406 * The following conditions are also required:
407 * - `data` must reference a contiguous, allocated, readable region of at
408 * least `word_count` words, violation of this will produce undefined
409 * behavior.
410 * - The first call to this function after starting the program transaction
411 * the same `word_count` must not exceed what was supplied at the start of
412 * the program transaction.
413 * - Each subsequent call the new `word_count` must not exceed `word_count -
414 * words_sent_out` from the previous call.
415 * All deviations on the above will produce a `kDifBadArg` error
416 * unless otherwise specified.
417 *
418 * If the FIFO fills up, this function will cause the CPU to block until the
419 * flash controller frees up more space.
420 *
421 * It is up to the caller to call `dif_flash_ctrl_end()` to ensure the
422 * flash controller completed this transaction successfully.
423 *
424 * @param handle flash controller device to push data to.
425 * @param word_count The number of words to write.
426 * @param data The data to write.
427 * program FIFO, will contain the number of words pushed.
428 * @return `kDifBadArg` if `handle` or `data` are null or if the value of
429 * `word_count` is illegal. `kDifError` if a program transaction was not
430 * started. `kDifOk` otherwise.
431 */
434 uint32_t word_count,
435 const uint32_t *data);
436
437/**
438 * Read data from the read FIFO. (unsafe version)
439 *
440 * This function is primarily for testing hardware error responses. If you are
441 * not specifically trying to force an error, consider
442 * `dif_flash_ctrl_read_fifo_pop()` instead. This function does not check if a
443 * transaction is currently in progress, nor if this would cause a read beyond
444 * the number of words for the current operation.
445 *
446 * Attempts to read `word_count` words from the read FIFO without consideration
447 * for the current controller state.
448 *
449 * It is up to the caller to call `dif_flash_ctrl_end()` to ensure the
450 * flash controller completed this transaction successfully.
451 *
452 * @param handle flash controller device to push data to.
453 * @param word_count The number of words to read.
454 * @param data_out The region in memory to store the data read off the FIFO.
455 * @return `kDifBadArg` if `handle` or `data` are null. `kDifOk` otherwise.
456 */
459 uint32_t word_count,
460 uint32_t *data_out);
461
462/**
463 * Read data from the read FIFO.
464 *
465 * Attempts to read `word_count` words from the read FIFO.
466 *
467 * The following conditions are required:
468 * - `data_out` must reference a contiguous, allocated, writable region of at
469 * least `word_count` words, violation of this will produce undefined
470 * behavior.
471 * - The first call to this function after starting the program transaction
472 * the same `word_count` must not exceed what was supplied at the start of
473 * the read transaction.
474 * - Each subsequent call the new `word_count` must not exceed `word_count -
475 * words_received` from the previous call.
476 * All deviations on the above will produce a `kDifBadArg` error unless
477 * otherwise specified.
478 *
479 * If the FIFO empties this function will cause the CPU to block until the flash
480 * controller fills the FIFO with more data.
481 *
482 * It is up to the caller to call `dif_flash_ctrl_end()` to ensure the
483 * flash controller completed this transaction successfully.
484 *
485 * @param handle flash controller device to pull data from.
486 * @param word_count The number of words to read.
487 * @param data_out The region in memory to store the data read off the FIFO.
488 * @param words_read_out Out-parameter, the number of words read.
489 * @return `kDifBadArg` if `handle` or `data_out` are null, or if the value of
490 * `word_count` is illegal. `kDifOk` otherwise.
491 */
494 uint32_t word_count,
495 uint32_t *data_out);
496
498 /**
499 * Access permission error.
500 */
502 /**
503 * Uncorrectable flash read data error.
504 */
505 bool read_error : 1;
506 /**
507 * Flash program has a window resolution error. In other words, the start of
508 * program and end of program are in different windows.
509 */
511 /**
512 * Flash program operation selected an unavailable type. For example, the
513 * repair type of programming was selected, but the flash did not support it.
514 */
516 /**
517 * A shadow register encountered an update error.
518 */
520} dif_flash_ctrl_error_codes_t;
521
522/**
523 * Represents recoverable errors and synchronous errors caused by software.
524 */
525typedef struct dif_flash_ctrl_error {
526 /**
527 * For errors associated with an address, the address where the error
528 * occurred.
529 */
530 uint32_t address;
531
532 /**
533 * A set of error codes.
534 */
535 dif_flash_ctrl_error_codes_t codes;
537
538/**
539 * Get the error codes and address of the last associated error.
540 *
541 * @param handle flash controller device to query.
542 * @param error_code_out Output parameter. The location where the current status
543 * is to be stored.
544 * @return `kDifBadArg` if `handle` or `error_code_out` are null. `kDifOk`
545 * otherwise.
546 */
549 const dif_flash_ctrl_state_t *handle,
550 dif_flash_ctrl_error_t *error_code_out);
551
552/**
553 * Clear the error codes.
554 *
555 * @param handle flash controller device to set.
556 * @return `kDifBadArg` if `handle` is null. `kDifOk` otherwise.
557 */
560 dif_flash_ctrl_state_t *handle, dif_flash_ctrl_error_codes_t codes);
561
562typedef struct dif_flash_ctrl_output {
563 /**
564 * The error code associated with an `operation_error`. This field is only
565 * valid if `operation_error` is true.
566 */
568 /**
569 * Flash operation done.
570 */
572 /**
573 * Flash operation error.
574 */
576
577} dif_flash_ctrl_output_t;
578
579/**
580 * Check that the transaction has completed and return any resulting error
581 * codes. Does not clear the error codes, but does clear the operation status if
582 * the operation has terminated.
583 *
584 * @param handle flash controller device for completing the transaction.
585 * @param out Out parameter. Contains the transaction status and error codes.
586 * @return `kDifBadArg` if `handle` or `out` are null, `kDifError` if no
587 * transaction was pending, `kDifUnavailable` if the controller is still
588 * processing the transaction, `kDifIpFifoFull` if there are still words
589 * remaining for the FIFOs, and `kDifOk` otherwise.
590 */
593 dif_flash_ctrl_output_t *out);
594
595/**
596 * Memory protection configuration options.
597 */
599 /** Read enable flag. */
600 multi_bit_bool_t rd_en;
601 /** Program enable flag. */
602 multi_bit_bool_t prog_en;
603 /** Erase enable flag. */
604 multi_bit_bool_t erase_en;
605 /** Scramble enable flag*/
606 multi_bit_bool_t scramble_en;
607 /** ECC enable flag. */
608 multi_bit_bool_t ecc_en;
609 /** High-endurance enable flag. */
610 multi_bit_bool_t high_endurance_en;
612
613/**
614 * A composite of a data region and its memory properties.
615 */
617 /** Region base page index. */
618 uint32_t base;
619 /** Region config size (in number of pages). */
620 uint32_t size;
621 /** Memory properties of the region. */
624
625/**
626 * Representation of the memory protection regions for the info pages.
627 */
629 /** Region bank ID. */
630 uint32_t bank;
631 /** Region info partition ID. */
632 uint32_t partition_id;
633 /** Region page index. */
634 uint32_t page;
636
637/**
638 * Enable/disable the data region of flash indexed by `region`.
639 *
640 * This may only be done if region configuration has not been locked.
641 *
642 * @param handle flash controller device to configure.
643 * @param region The region to operate on.
644 * @param enable Enable or disable this `region`.
645 * @return `kDifBadArg` if `handle` is null or `region` is invalid, `kDifLocked`
646 * if region configuration has been locked, and `kDifOk` otherwise.
647 */
650 dif_flash_ctrl_state_t *handle, uint32_t region, dif_toggle_t enable);
651
652/**
653 * Get the enabled/disabled state for the indicated data `region`.
654 *
655 * @param handle flash controller device to query.
656 * @param region The region in question.
657 * @param enabled_out Out-parameter, the enabled/disabled state of this region.
658 * @return `kDifBadArg ` if `handle` or `enabled_out` is null, or if `region` is
659 * invalid, `kDifOk` otherwise.
660 */
663 const dif_flash_ctrl_state_t *handle, uint32_t region,
664 dif_toggle_t *enabled_out);
665
666/**
667 * Enable/disable the info region of flash identified by `region`.
668 *
669 * This may only be done if region configuration has not been locked.
670 *
671 * @param handle flash controller device to configure.
672 * @param region The region to operate on.
673 * @param enable Enable or disable this `region`.
674 * @return `kDifBadArg` if `handle` is null or `region` is invalid, `kDifLocked`
675 * if region configuration has been locked, and `kDifOk` otherwise.
676 */
680 dif_toggle_t enable);
681
682/**
683 * Get the enabled/disabled state for the indicated info `region`.
684 *
685 * @param handle flash controller device to query.
686 * @param region The region in question.
687 * @param enabled_out Out-parameter, the enabled/disabled state of this region.
688 * @return `kDifBadArg ` if `handle` or `enabled_out` is null, or if `region` is
689 * invalid, `kDifOk` otherwise.
690 */
694 dif_toggle_t *enabled_out);
695
696/**
697 * Set the default memory properties for data regions, when not overridden by a
698 * specific entry in the data region memory properties table.
699 *
700 * @param handle flash controller device to configure.
701 * @param properties The memory properties to control.
702 * @return `kDifBadArg` if `handle` is null, `kDifOk` otherwise.
703 */
708
709/**
710 * Get the default memory properties for data regions, when they are not
711 * overridden by a specific entry in the data region memory properties table.
712 *
713 * @param handle flash controller device to query.
714 * @param properties_out Out-parameter, a pointer to a
715 * `dif_flash_ctrl_region_properties_t` struct for writing the memory
716 * properties.
717 * @return `kDifBadArg` if `handle` or `properties_out` are null. `kDifOk`
718 * otherwise.
719 */
722 const dif_flash_ctrl_state_t *handle,
723 dif_flash_ctrl_region_properties_t *properties_out);
724
725/**
726 * Set memory properties for the data region of flash indexed by `region`.
727 *
728 * This may only be done if region configuration has not been locked.
729 *
730 * @param handle flash controller device to configure.
731 * @param region The region to operate on.
732 * @param config The memory properties to control for this `region`.
733 * @return `kDifBadArg` if `handle` is null or `region` is invalid, `kDifLocked`
734 * if region configuration has been locked, and `kDifOk` otherwise.
735 */
738 dif_flash_ctrl_state_t *handle, uint32_t region,
740
741/**
742 * Get the memory properties for the data region of flash indexed by `region`.
743 *
744 * @param handle flash controller device to query.
745 * @param region The index of the region entry in question.
746 * @param config_out Out-parameter, a pointer to a
747 * `dif_flash_ctrl_data_region_properties_t` struct for writing the full entry
748 * showing the region configuration and its memory properties.
749 * @return `kDifBadArg` if `handle` or `properties_out` are null or if `region`
750 * is invalid. `kDifOk` otherwise.
751 */
754 const dif_flash_ctrl_state_t *handle, uint32_t region,
756
757/**
758 * Set memory properties for the info region of flash identified by `region`.
759 *
760 * This may only be done if region configuration has not been locked.
761 *
762 * @param handle flash controller device to configure.
763 * @param region The region to operate on.
764 * @param properties The memory properties to control for this `region`.
765 * @return `kDifBadArg` if `handle` is null or `region` is invalid, `kDifLocked`
766 * if region configuration has been locked, and `kDifOk` otherwise.
767 */
772
773/**
774 * Get the memory properties for the info region of flash identified by
775 * `region`.
776 *
777 * @param handle flash controller device to query.
778 * @param region The index of the region entry in question.
779 * @param properties_out Out-parameter, a pointer to a
780 * `dif_flash_ctrl_region_properties_t` struct for writing memory properties
781 * associated with the indicated `region`.
782 * @return `kDifBadArg` if `handle` or `properties_out` are null or if `region`
783 * is invalid. `kDifOk` otherwise.
784 */
788 dif_flash_ctrl_region_properties_t *properties_out);
789
790/**
791 * Lock data region memory properties configuration until the device is reset.
792 *
793 * This will prevent any further configuration of region properties until device
794 * reset. Future calls to functions that set data region memory properties will
795 * return `kDifLocked`.
796 *
797 * @param handle flash controller device to lock region configuration on.
798 * @param region The region to lock.
799 * @return `kDifBadArg` if `handle` is null, or if `region` is invalid,
800 * `kDifLocked` if configuration is already locked, `kDifOk` otherwise.
801 */
804 dif_flash_ctrl_state_t *handle, uint32_t region);
805
806/**
807 * Lock info region memory properties configuration until the device is reset.
808 *
809 * This will prevent any further configuration of region properties until device
810 * reset. Future calls to functions that set info region memory properties will
811 * return `kDifLocked`.
812 *
813 * @param handle flash controller device to lock region configuration on.
814 * @param region The region to lock.
815 * @return `kDifBadArg` if `handle` is null, or if `region` is invalid,
816 * `kDifLocked` if configuration is already locked, `kDifOk` otherwise.
817 */
821
822/**
823 * Query the state of the region configuration lock for the given data `region`
824 * entry's index.
825 *
826 * This function checks if memory region configuration is still enabled or if it
827 * has been locked. Once locked, region configuration cannot be enabled again,
828 * and all calls to region configuration functions will return `kDifLocked`
829 * until the device is restarted.
830 *
831 * @param handle flash controller device to check the lock state for.
832 * @param region The region in question.
833 * @param locked_out Out-parameter, the current state of the region's
834 * configuration lock.
835 * @return `kDifBadArg` if `handle` or `locked_out` is null, or if `region` is
836 * invalid, `kDifOk` otherwise.
837 */
840 const dif_flash_ctrl_state_t *handle, uint32_t region, bool *locked_out);
841
842/**
843 * Query the state of the region configuration lock for the given info `region`.
844 *
845 * This function checks if memory region configuration is still enabled or if it
846 * has been locked. Once locked, region configuration cannot be enabled again,
847 * and all calls to region configuration functions will return `kDifLocked`
848 * until the device is restarted.
849 *
850 * @param handle flash controller device to check the lock state for.
851 * @param region The region in question.
852 * @param locked_out Out-parameter, the current state of the region's
853 * configuration lock.
854 * @return `kDifBadArg` if `handle` or `locked_out` is null, or if `region` is
855 * invalid, `kDifOk` otherwise.
856 */
860 bool *locked_out);
861
862/**
863 * Enable/disable erase operations for a particular flash bank.
864 *
865 * This may only be done if bank configuration is still enabled.
866 *
867 * @param handle flash controller device to operate on.
868 * @param bank The bank to configure.
869 * @param enable Enable/disable erase access for this bank.
870 * @return `kDifBadArg` if `handle` is null or `bank` is invalid, `kDifLocked`
871 * if bank configuration is locked, and `kDifOk` otherwise.
872 */
875 dif_flash_ctrl_state_t *handle, uint32_t bank, dif_toggle_t enable);
876
877/**
878 * Query the erase permissions for a particular flash bank.
879 *
880 * @param handle flash controller device to query.
881 * @param bank The bank to query.
882 * @param enabled_out Out-parameter, the erase permissions for this bank.
883 * @return `kDifBadArg` if `handle` or `enabled_out` is null and `kDifOk`
884 * otherwise.
885 */
888 const dif_flash_ctrl_state_t *handle, uint32_t bank,
889 dif_toggle_t *enabled_out);
890
891/**
892 * Lock bank configuration until the device is reset.
893 *
894 * This will prevent any further configuration of memory banks until device
895 * reset. Future calls to bank configuration functions will return `kDifLocked`.
896 *
897 * @param handle flash controller device to lock region configuration on.
898 * @return `kDifBadArg` if `handle` is null, `kDifLocked` if already locked,
899 * and `kDifOk` otherwise.
900 */
903 dif_flash_ctrl_state_t *handle);
904
905/**
906 * Query the state of the bank configuration lock.
907 *
908 * This function checks if memory bank configuration is still enabled or if it
909 * has been locked. Once locked, bank configuration cannot be enabled again, and
910 * all calls to bank configuration functions will return `kDifLocked` until the
911 * device is restarted.
912 *
913 * @param handle flash controller device to check the lock state for.
914 * @param locked_out Out-parameter, the current state of the bank configuration
915 * lock.
916 * @return `kDifBadArg` if `handle` or `locked_out` is null, `kDifOk` otherwise.
917 */
920 const dif_flash_ctrl_state_t *handle, bool *locked_out);
921
922/**
923 * Set the interrupt watermarks for the program FIFO.
924 *
925 * The value of `level` defines the level the program FIFO must drain to before
926 * triggering a `prog_lvl` interrupt.
927 *
928 * This interrupts will only trigger if enabled through the interrupt API.
929 *
930 * @param handle flash controller to set FIFO level watermarks for.
931 * @param prog Trigger an interrupt when the program FIFO drains to this level.
932 * @return `kDifBadArg` if `handle` is null or if the value `level` is out of
933 * range, `kDifOk` otherwise.
934 */
937 dif_flash_ctrl_state_t *handle, uint32_t level);
938
939/**
940 * Set the interrupt watermarks for the read FIFO.
941 *
942 * The value of `level` defines the level the read FIFO must fill to before
943 * triggering a `rd_lvl` interrupt.
944 *
945 * This interrupt will only trigger if enabled through the interrupt API.
946 *
947 * @param handle flash controller to set FIFO level watermarks for.
948 * @param level Trigger an interrupt when the read FIFO fills to this level.
949 * @return `kDifBadArg` if `flash_ctrl` is null or if the value of `prog` is out
950 * of range, `kDifOk` otherwise.
951 */
954 dif_flash_ctrl_state_t *handle, uint32_t level);
955
956/**
957 * Get the interrupt watermarks for the program and read FIFOs.
958 *
959 * @param handle flash controller to get FIFO level watermarks from.
960 * @param prog_out Out-parameter, the prog FIFO watermark level. If the prog
961 * FIFO empties to this level, a corresponding status bit and possibly an
962 * interrupt may be generated. May be null.
963 * @param read_out Out-parameter, the read FIFO watermark level. If the read
964 * FIFO fills to this level, a corresponding status bit and possibly an
965 * interrupt may be generated. May be null.
966 * @return `kDifBadArg` if `handle` is null, `kDifOk` otherwise.
967 */
970 const dif_flash_ctrl_state_t *handle, uint32_t *prog_out,
971 uint32_t *read_out);
972
973/**
974 * Resets both the program and read FIFOs.
975 *
976 * This is useful in the event of an unexpected error as a means of reseting
977 * state.
978 *
979 * @param handle flash controller device to clear FIFOs on.
980 * @return `kDifBadArg` if `handle` is null, `kDifOk` otherwise.
981 */
984
985typedef struct dif_flash_ctrl_faults {
986 /** The flash hardware interface encountered a memory permission error. */
988 /** The flash hardware interface encountered a read data error. */
989 bool read_error : 1;
990 /** The flash hardware interface encountered a program resolution error. */
992 /** The flash hardware interface encountered a program type error. */
994 /** A host transaction was granted with illegal properties. */
996 /** The flash controller encountered a register integrity error. */
998 /** The flash memory encountered a register integrity error. */
1000 /** The lifecycle management interface encountered a fatal error. */
1002 /** A shadow register encountered a storage fault. */
1004} dif_flash_ctrl_faults_t;
1005
1006/**
1007 * Gets the unrecoverable or hardware faults.
1008 *
1009 * @param handle flash controller device to query
1010 * @param faults_out Out parameter, a pointer to the location to write the fault
1011 * values.
1012 * @return `kDifBadArg` if `handle` or `fault_out` are null. `kDifOk` otherwise.
1013 */
1016 dif_flash_ctrl_faults_t *faults_out);
1017
1019 /** Count of the number of single-bit ECC errors. */
1021 /** The last address that produced a single-bit ECC error. */
1023} dif_flash_ctrl_ecc_errors_t;
1024
1025/**
1026 * Get the ECC error information for the specified flash `bank`.
1027 *
1028 * @param handle The flash controller device to query.
1029 * @param bank The desired bank to look up errors for.
1030 * @return `kDifBadArg` if `handle` or `errors_out` are null or if `bank` is
1031 * invalid. `kDifOk` otherwise.
1032 */
1035 const dif_flash_ctrl_state_t *handle, uint32_t bank,
1036 dif_flash_ctrl_ecc_errors_t *errors_out);
1037
1039 /** Flash phy controller is initializing. */
1041 /** Normal programming is supported. */
1043 /** Repair programming is supported. */
1045} dif_flash_ctrl_phy_status_t;
1046
1047/**
1048 * Query the status registers on the flash controller.
1049 *
1050 * This function checks the various status bits as described in
1051 * `dif_flash_ctrl_phy_status_t`.
1052 *
1053 * @param handle The flash controller device with the desired phy's status bit
1054 * to check.
1055 * @param status_out Out-parameter, the current status of the flash phy.
1056 * @return `kDifBadArg` if `handle` or `status_out` is null, `kDifOk`
1057 * otherwise.
1058 */
1061 const dif_flash_ctrl_state_t *handle,
1062 dif_flash_ctrl_phy_status_t *status_out);
1063
1064/**
1065 * Set the value of the scratch register.
1066 *
1067 * @param handle The flash controller device to operate on.
1068 * @param value The value to set the scratch register to.
1069 * @return `kDifBadArg` if `handle` is null, `kDifOk` otherwise.
1070 */
1073 uint32_t value);
1074
1075/**
1076 * Get the value of the scratch register.
1077 *
1078 * @param handle The flash controller device to query.
1079 * @param value_out Out parameter. The location to write the scratch register's
1080 * value to.
1081 * @return `kDifBadArg` if `handle` or `value_out` are null. `kDifOk` otherwise.
1082 */
1085 uint32_t *value_out);
1086
1087// TODO: PHY alerts, which are separate from the autogenerated alerts.
1088
1089#ifdef __cplusplus
1090} // extern "C"
1091#endif // __cplusplus
1092
1093#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_FLASH_CTRL_H_