Software APIs
dif_spi_device.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_SPI_DEVICE_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_SPI_DEVICE_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/spi_device/doc/">SPI Device</a> Device Interface
11  * Functions
12  */
13 
14 #include <stddef.h>
15 #include <stdint.h>
16 
20 
21 #include "sw/device/lib/dif/autogen/dif_spi_device_autogen.h"
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif // __cplusplus
26 
27 /**
28  * The mode that the spi device operates in.
29  */
30 typedef enum dif_spi_device_mode {
31  /**
32  * spi_device will ignore all transactions in this mode configuration.
33  */
35  /**
36  * In flash emulation mode, the hardware behaves like a SPI NOR flash device.
37  */
39  /**
40  * In pass-through mode, the hardware forwards commands to another SPI flash
41  * device, with various tables providing rules for filtering and forwarding.
42  * The hardware may be configured to also behave like a SPI NOR flash device,
43  * with some commands and/or address regions targeting internal handling,
44  * instead of being passed through.
45  */
48 
49 /**
50  * A bit ordering within a byte.
51  */
53  /**
54  * Represents the most-significant-bit to least-significant-bit order.
55  */
57  /**
58  * Represents the least-significant-bit to most-significant-bit order.
59  */
62 
63 /**
64  * Runtime configuration for SPI.
65  *
66  * This struct describes runtime information for one-time configuration of the
67  * hardware.
68  */
69 typedef struct dif_spi_device_config {
72  dif_spi_device_mode_t device_mode;
74 
75 /**
76  * Struct containing the relevant run-time information for the DIF.
77  */
78 typedef struct dif_spi_device_handle {
79  /**
80  * Device information of the hardware.
81  */
82  dif_spi_device_t dev;
83  /**
84  * Configuration information of the hardware.
85  */
88 
89 /**
90  * The length of the SPI device FIFO buffer, in bytes.
91  *
92  * Useful for initializing FIFO lengths: for example, for equally-sized FIFOs,
93  * `rx_fifo_len` and `tx_fifo_len` would be set to `kDifSpiDeviceBufferLen / 2`.
94  */
95 extern const uint16_t kDifSpiDeviceBufferLen;
96 
97 /**
98  * Initializes a SPI device handle for use.
99  *
100  * @param base_addr The MMIO base address of the spi_device peripheral.
101  * @param[out] spi Out param for the initialized handle.
102  * @return The result of the operation.
103  */
107 
108 /**
109  * Initializes a SPI device handle for use.
110  *
111  * @param dt The DT handle of the spi_device peripheral.
112  * @param[out] spi Out param for the initialized handle.
113  * @return The result of the operation.
114  */
118 
119 /**
120  * Configures SPI with runtime information.
121  *
122  * This function should need to be called once for the lifetime of `handle`.
123  *
124  * @param spi A SPI handle.
125  * @param config Runtime configuration parameters.
126  * @return The result of the operation.
127  */
130  dif_spi_device_config_t config);
131 
132 /**
133  * Turn on/off passthrough without changing any other configuration.
134  *
135  * This changes the mode to one of flash mode or passthrough mode. The current
136  * mode must be one of those, else this function will fail.
137  *
138  * @param spi A SPI handle.
139  * @param enable Whether to turn on passthrough mode.
140  * @return The result of the operation.
141  */
144  dif_toggle_t enable);
145 
146 /**
147  * Get the current level of the CSB pin.
148  *
149  * This is available for the esoteric case where CSB is used like a slow GPIO.
150  * Note that for ordinary SPI operation, software sampling of the CSB pin cannot
151  * be used to determine whether it is safe to perform an operation where the
152  * host must be inactive.
153  *
154  * @param spi A SPI handle.
155  * @param[out] csb The current value of the chip-select pin (false for asserted,
156  * true for deasserted).
157  * @return The result of the operation.
158  */
161  bool *csb);
162 
163 /**
164  * Enable the mailbox region for spi_device flash / passthrough modes.
165  *
166  * Allocate 1 KiB for the mailbox, starting from the provided base `address`.
167  *
168  * @param spi A SPI device.
169  * @param address The base address of the 1 KiB mailbox. The lower 10 bits are
170  * ignored.
171  * @return kDifBadArg if spi is null, else kDifOk.
172  */
175  uint32_t address);
176 
177 /**
178  * Disable the mailbox region for spi_device flash / passthrough modes.
179  *
180  * @param spi A SPI device.
181  * @return kDifBadArg if spi is null, else kDifOk.
182  */
185 
186 /**
187  * Get the active configuration for the mailbox region.
188  *
189  * @param spi A SPI device.
190  * @param[out] is_enabled Whether the mailbox region is enabled.
191  * @param[out] address If the mailbox is enabled, the base address of the
192  * mailbox region.
193  * @return kDifBadArg if any argument is null, else kDifOk.
194  */
197  dif_spi_device_handle_t *spi, dif_toggle_t *is_enabled, uint32_t *address);
198 
199 /**
200  * Set the address mode of the SPI device in flash/passthrough mode.
201  *
202  * @param spi A SPI device.
203  * @param addr_4b If kDifToggleEnabled, set the address mode to 4 Bytes.
204  * Otherwise, set the address mode to 3 Bytes.
205  * @return kDifBadArg if spi is NULL or addr_4b is not a valid toggle. kDifOk
206  * otherwise.
207  */
210  dif_toggle_t addr_4b);
211 /**
212  * Get the address mode of the SPI device in flash/passthrough mode.
213  *
214  * @param spi A SPI device.
215  * @param[out] addr_4b Points to toggle that will be set to `kDifToggleEnabled`
216  * if the device is in 4-byte address mode, else `kDifToggleDisabled`.
217  * @return kDifBadArg if spi or addr_4b are NULL. kDifOk otherwise.
218  */
221  dif_toggle_t *addr_4b);
222 
223 /**
224  * Clear any pending software-originated flash status change requests.
225  *
226  * @param spi A SPI device.
227  * @return kDifBadArg if spi is NULL. kDifOk otherwise.
228  */
232 
233 typedef struct dif_spi_device_flash_id {
234  /** The device ID for the SPI flash. */
235  uint16_t device_id;
236  /** The JEDEC manufacturer ID. */
238  /** The continuation code used before the `manufacturer_id` byte. */
240  /** The number of continuation codes preceding the `manufacturer_id`. */
243 
244 /**
245  * Get the JEDEC ID presented when in flash / passthrough modes.
246  *
247  * @param spi A SPI device.
248  * @param[out] id Points to location that will be set to the current JEDEC ID.
249  * @return kDifBadArg if spi or id are NULL. kDifOk otherwise.
250  */
254 /**
255  * Set the JEDEC ID presented when in flash / passthrough modes.
256  *
257  * @param spi A SPI device.
258  * @param id The JEDEC ID to set.
259  * @return kDifBadArg if spi is NULL. kDifOk otherwise.
260  */
264 
265 /**
266  * Represents which optional hardware features may intercept commands in
267  * passthrough mode. If selected, the function will be handled internally and
268  * not passed to the downstream SPI flash (sometimes with conditions, such as
269  * the address matching the mailbox region when mailbox interception is
270  * selected).
271  */
273  /**
274  * Whether to intercept commands to the status registers, such as WriteStatus
275  * and ReadStatus.
276  */
277  bool status;
278  /**
279  * Whether to intercept the ReadID command and respond with the JEDEC ID
280  * programmed via `dif_spi_device_set_flash_id()`.
281  */
282  bool jedec_id;
283  /**
284  * Whether to intercept the ReadSFDP command with data programmed to the
285  * internal SFDP region.
286  */
287  bool sfdp;
288  /**
289  * Whether to intercept read memory commands with data programmed in the
290  * mailbox buffer, when the address is inside the mailbox region.
291  */
292  bool mailbox;
294 
295 /**
296  * Configure the optional hardware functions to intercept passthrough commands.
297  *
298  * @param spi A SPI handle.
299  * @param config The passthrough interception configuration.
300  * @return The result of the operation.
301  */
306 
307 /**
308  * Get the last address read from the flash memory that was not in the mailbox
309  * region.
310  *
311  * @param spi A SPI handle.
312  * @param[out] address The last address read.
313  * @return The result of the operation.
314  */
317  uint32_t *address);
318 
319 /**
320  * Set the read threshold watermark for reporting to the corresponding interrupt
321  * status bit.
322  *
323  * This function is intended to be used in flash mode for devices that
324  * sequentially read from address 0 to the end of some initial block. A supplied
325  * address of 0 disables the watermark status bit and interrupt.
326  *
327  * @param spi A SPI handle.
328  * @param address The watermark address that triggers reporting to the read
329  * threshold watermark's status bit, which can signal an interrupt.
330  * @return The result of the operation.
331  */
334  dif_spi_device_handle_t *spi, uint32_t address);
335 
336 /**
337  * Clear eflash read buffer state.
338  *
339  * Reinitialize the eflash read buffer to initial state.
340  *
341  * @param spi A SPI device.
342  * @return kDifBadArg if spi is NULL. kDifOk otherwise.
343  */
346 
348  /** No address for this command */
350  /** Address size for this command is determined by the current address mode */
352  /** Address size for this command is fixed at 3 bytes */
354  /** Address size for this command is fixed at 4 bytes */
356  kDifSpiDeviceFlashAddrCount,
357 } dif_spi_device_flash_address_type_t;
358 
359 /** An enum describing the type of I/O width used by a command's payload. */
361  /** Command does not have a payload. */
363  /** Command's payload has an I/O channel width of 1. */
365  /** Command's payload has an I/O channel width of 2. */
367  /** Command's payload has an I/O channel width of 4. */
369  /** The command info slot had an invalid setting for the payload I/O width. */
372 
374  /** No additional flash payload read pipeline stages. */
376  /**
377  * Add 2-stage pipeline to command read output. Perform half-cycle sampling on
378  * the incoming data.
379  */
381  /**
382  * Add 2-stage pipeline to command read output. Perform full-cycle sampling on
383  * the incoming data.
384  */
386  kDifSpiDeviceReadPipelineModeCount,
387 } dif_spi_device_read_pipeline_mode_t;
388 
390  /** The opcode for this command. */
391  uint8_t opcode;
392  /* The presence and type of the address phase of this command. */
393  dif_spi_device_flash_address_type_t address_type;
394  /** The number of dummy cycles between the address phase and the payload phase
395  * of a command. Note that if `payload_io_width` is
396  * `kDifSpiDevicePayloadIoNone`, a nonzero value may cause undefined behavior,
397  * possibly including the device assuming dummy cycles are part of this
398  * payload-less command.
399  */
400  uint8_t dummy_cycles;
401  /** The I/O width for the payload phase of this command. */
403  /**
404  * Whether to translate the address using the address swap mask and value
405  * provided to `dif_spi_device_passthrough_set_swap_address()`. Incompatible
406  * with a command with `address_type` that is
407  * `kDifSpiDeviceFlashAddrDisabled`.
408  */
410  /** Whether the SPI host is receiving this command's payload phase. */
412  /** Whether to swap up to the first 32 bits of the payload. */
414  /** The read payload pipeline mode to use for this command. */
415  dif_spi_device_read_pipeline_mode_t read_pipeline_mode;
416  /** Whether to upload the command to the payload FIFO. */
417  bool upload;
418  /** Whether to set the busy bit in the status register. */
421 
423  /** eFlash region */
425  /** Mailbox region */
427  /** SFDP region */
429  /** Count of buffer types */
431 } dif_spi_device_flash_buffer_type_t;
432 
433 /**
434  * Set up the indicated command info slot for flash / passthrough modes.
435  *
436  * @param spi A handle to a spi device.
437  * @param slot A command info slot ID.
438  * @param enable Whether to enable or disable the command slot.
439  * @param command_info If `enable` is set, provides the configuration for the
440  * command.
441  * @return `kDifBadArg` if `spi` is NULL or `slot` is larger than the number of
442  * command slots. `kDifOk` otherwise.
443  */
446  dif_spi_device_handle_t *spi, uint8_t slot, dif_toggle_t enable,
447  dif_spi_device_flash_command_t command_info);
448 
449 /**
450  * Get the current configuration of the indicated command info slot.
451  *
452  * @param spi A handle to a spi device.
453  * @param slot A command info slot ID.
454  * @param[out] enabled A pointer to where the current slot state can be stored.
455  * @param[out] command_info If `enabled`, points to where the current command
456  * configuration can be stored.
457  * @return `kDifBadArg` if any pointers are NULL or `slot` is larger than the
458  * number of command slots. `kDifOk` otherwise.
459  */
462  dif_spi_device_handle_t *spi, uint8_t slot, dif_toggle_t *enabled,
463  dif_spi_device_flash_command_t *command_info);
464 
465 /**
466  * Configure the command properties of the hardware's EN4B function.
467  *
468  * EN4B is the command to activate 4-byte addressing for flash and passthrough
469  * modes.
470  *
471  * @param spi A handle to a spi_device.
472  * @param enable Whether to enable the function.
473  * @param opcode Which opcode activates the function.
474  * @return The result of the operation.
475  */
478  dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode);
479 
480 /**
481  * Configure the command properties of the hardware's EX4B function.
482  *
483  * EX4B is the command to deactivate 4-byte addressing for flash and passthrough
484  * modes. This would return the device to the 3-byte address mode.
485  *
486  * @param spi A handle to a spi_device.
487  * @param enable Whether to enable the function.
488  * @param opcode Which opcode activates the function.
489  * @return The result of the operation.
490  */
493  dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode);
494 
495 /**
496  * Configure the command properties of the hardware's WREN function.
497  *
498  * WREN is the command to enable writes and set the WEL bit of the status
499  * register, for flash and passthroug modes.
500  *
501  * @param spi A handle to a spi_device.
502  * @param enable Whether to enable the function.
503  * @param opcode Which opcode activates the function.
504  * @return The result of the operation.
505  */
508  dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode);
509 
510 /**
511  * Configure the command properties of the hardware's WRDI function.
512  *
513  * WRDI is the command to disable writes and clear the WEL bit of the status
514  * register, for flash and passthrough modes.
515  *
516  * @param spi A handle to a spi_device.
517  * @param enable Whether to enable the function.
518  * @param opcode Which opcode activates the function.
519  * @return The result of the operation.
520  */
523  dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode);
524 
525 /**
526  * Set which address bits are swapped and their values for commands that have
527  * the address swap enabled.
528  *
529  * @param spi A handle to a spi device.
530  * @param mask A bitmask indicating which address bits should be replaced.
531  * @param replacement The values to swap in for the masked address bits.
532  * @return `kDifBadArg` if spi is NULL, else `kDifOk`.
533  */
536  uint32_t mask,
537  uint32_t replacement);
538 
539 /**
540  * Set which bits are swapped and their values for commands that have
541  * the first-word payload swap function enabled.
542  *
543  * @param spi A handle to a spi device.
544  * @param mask A bitmask indicating which bits should be replaced.
545  * @param replacement The values to swap in for the masked bits.
546  * @return `kDifBadArg` if spi is NULL, else `kDifOk`.
547  */
550  uint32_t mask,
551  uint32_t replacement);
552 
553 /**
554  * Get the current occupancy level of the command FIFO. Used in flash and
555  * passthrough modes.
556  *
557  * @param spi A SPI handle.
558  * @param[out] occupancy The number of command entries present in the command
559  * FIFO.
560  * @return The result of the operation.
561  */
564  dif_spi_device_handle_t *spi, uint8_t *occupancy);
565 
566 /**
567  * Get the current occupancy level of the address FIFO. Used in flash and
568  * passthrough modes.
569  *
570  * @param spi A SPI handle.
571  * @param[out] occupancy The number of address entries present in the command
572  * FIFO.
573  * @return The result of the operation.
574  */
577  dif_spi_device_handle_t *spi, uint8_t *occupancy);
578 
579 /**
580  * Get the current occupancy level of the payload FIFO. Used in flash and
581  * passthrough modes.
582  *
583  * Also get the starting offset for the data that was captured. Only up to 256
584  * bytes of payload may be captured by the SPI device, and if the SPI host sends
585  * more data, the SPI device wraps around to the beginning of the payload buffer
586  * and writes the newest data from there. The starting offset points to the
587  * oldest item in the payload buffer.
588  *
589  * @param spi A SPI handle.
590  * @param[out] occupancy The number of bytes present in the command FIFO.
591  * @param[out] start_offset The starting offset in the payload buffer for the
592  * data, which may wrap around to the beginning.
593  * @return The result of the operation.
594  */
597  dif_spi_device_handle_t *spi, uint16_t *occupancy, uint32_t *start_offset);
598 
599 /**
600  * Pop the first command from the uploaded command FIFO.
601  *
602  * @param spi A handle to a spi device.
603  * @param[out] command A pointer to where the command can be stored.
604  * @return `kDifBadArg` if any pointers are NULL. `kDifUnavailable` if the FIFO
605  * was empty. `kDifOk` otherwise.
606  */
609  uint8_t *command);
610 
611 /**
612  * Pop the first address from the uploaded address FIFO.
613  *
614  * @param spi A handle to a spi device.
615  * @param[out] address A pointer to where the address can be stored.
616  * @return `kDifBadArg` if any pointers are NULL. `kDifUnavailable` if the FIFO
617  * was empty. `kDifOk` otherwise.
618  */
621  uint32_t *address);
622 
623 /**
624  * Read data from the payload buffer associated with flash / passthrough modes.
625  *
626  * @param spi A handle to a spi device.
627  * @param offset The starting offset for read data in the memory.
628  * @param length The length, in bytes, of the data to be copied.
629  * @param[out] buf A pointer to the location where the data should be stored.
630  * @return `kDifBadArg` is any pointers are NULL or the `buffer_type` does not
631  * exist. `kDifOutOfRange` if the requested `offset` and `length` go beyond the
632  * payload buffer region. `kDifOk` otherwise.
633  */
636  dif_spi_device_handle_t *spi, uint32_t offset, size_t length, uint8_t *buf);
637 
638 /**
639  * Write data to one of the memories associated with flash / passthrough modes.
640  *
641  * @param spi A handle to a spi device.
642  * @param buffer_type An identifier for which memory space to write to.
643  * @param offset The starting offset for the write location of the data.
644  * @param length The length, in bytes, of the data to be copied.
645  * @param buf A pointer to the location where the data can be copied from.
646  * @return `kDifBadArg` is any pointers are NULL or the `buffer_type` does not
647  * exist. `kDifOutOfRange` if the requested `offset` and `length` go beyond the
648  * indicated `buffer_type` region. `kDifOk` otherwise.
649  */
653  dif_spi_device_flash_buffer_type_t buffer_type, uint32_t offset,
654  size_t length, const uint8_t *buf);
655 
656 /**
657  * Get whether the indicated command is filtered for passthrough.
658  *
659  * @param spi A handle to a spi device.
660  * @param command The command to be queried.
661  * @param[out] enabled A pointer to a location where the filter status can be
662  * stored. `kDifEnabled` means the command is filtered.
663  * @return `kDifBadArg` if any pointers are NULL. `kDifOk` otherwise.
664  */
667  dif_spi_device_handle_t *spi, uint8_t command, dif_toggle_t *enabled);
668 
669 /**
670  * Set whether the indicated command is filtered for passthrough.
671  *
672  * @param spi A handle to a spi device.
673  * @param command The command to have its filter status updated.
674  * @param enable Whether to enable the command filter for the `command`.
675  * @return `kDifBadArg` if `spi` is NULL or `enable` is invalid. `kDifOk`
676  * otherwise.
677  */
680  dif_spi_device_handle_t *spi, uint8_t command, dif_toggle_t enable);
681 
682 /**
683  * Set whether ALL commands are filtered for passthrough.
684  *
685  * Can be used for a faster initial state before using
686  * `dif_spi_device_set_passthrough_command_filter` to set the filter status for
687  * individual commands.
688  *
689  * @param spi A handle to a spi device.
690  * @param enable Whether to enable the command filter for all commands.
691  * @return `kDifBadArg` if `spi` is NULL or `enable` is invalid. `kDifOk`
692  * otherwise.
693  */
697 
698 /**
699  * Clear the busy bit and write-enable bit for flash / passthrough modes.
700  *
701  * @param spi A handle to a spi device.
702  * @return `kDifBadArg` if `spi` is NULL. `kDifOk` otherwise.
703  */
706 
707 /**
708  * Write the status registers for flash / passthrough modes.
709  *
710  * Note that the three registers are concatenated to make one 24-bit value, with
711  * the LSB being the busy bit.
712  *
713  * @param spi A handle to a spi device.
714  * @param value The value to write to the registers.
715  * @return `kDifBadArg` if `spi` is NULL. `kDifOk` otherwise.
716  */
719  dif_spi_device_handle_t *spi, uint32_t value);
720 
721 /**
722  * Get the values of the status registers for flash / passthrough modes.
723  *
724  * Note that the three registers are concatenated to make one 24-bit value, with
725  * the LSB being the busy bit.
726  *
727  * @param spi A handle to a spi device.
728  * @param[out] value A pointer to where to write the values of the registesr.
729  * @return `kDifBadArg` if any pointer arguments are NULL. `kDifOk` otherwise.
730  */
733  dif_spi_device_handle_t *spi, uint32_t *value);
734 
735 typedef struct dif_spi_device_tpm_caps {
736  /** Hardware revision of the TPM submodule. */
737  uint8_t revision;
738  /**
739  * True if the TPM supports 5 Locality. Otherwise, only 1 Locality is
740  * supported.
741  */
743  /**
744  * The maximum write size, in bytes, of the data phase of TPM
745  * transactions. This represents the maximum amount of data the FIFO can
746  * accept.
747  */
748  uint8_t max_write_size;
749  /**
750  * The maximum read size, in bytes, of the data phase of TPM
751  * transactions. This represents the maximum amount of data the FIFO can
752  * accept.
753  */
754  uint8_t max_read_size;
756 
757 /**
758  * Read the capabilities of the TPM hardware IP.
759  *
760  * @param spi A handle to a spi device.
761  * @param[out] caps The TPM's hardware capabilities.
762  * @return The result of the operation.
763  */
767 
769  /** Specifies the FIFO interface from the TPM specification. */
771  /** Specifies the CRB interface from the TPM specification. */
773  kDifSpiDeviceTpmInterfaceCount,
774 } dif_spi_device_tpm_interface_t;
775 
777  /**
778  * The register interface to implement for the TPM. Note that in CRB mode, the
779  * return-by-hardware logic is disabled.
780  */
781  dif_spi_device_tpm_interface_t interface;
782  /**
783  * Upload the commands that would ordinarily be targeted towards registers
784  * that automatically return by hardware. This includes TPM_DID_VID_x,
785  * TPM_RID_x, TPM_STS_x, and TPM_ACCESS_x.
786  */
788  /**
789  * Disable address prefix check that matches the pattern 0xD4_XXXX before
790  * using the return-by-hardware logic. When true, the upper 8 bits of the
791  * address are not required to be 0xD4 for the return-by-hardware logic to
792  * activate. When false, commands with non-matching addresses will be
793  * uploaded.
794  */
796  /**
797  * Disable locality value check to be within the max value before using the
798  * return-by-hardware logic. When true, the TPM will return 0xFF-valued data
799  * on reads and discard writes to registers in the TPM region (matching the
800  * 0xD4_XXXX address pattern) if the locality value is above the maximum. When
801  * false, commands with invalid locality will be uploaded, and software would
802  * be responsible for returning 0xFF to read requests.
803  */
806 
807 /**
808  * Configure the TPM within a SPI device.
809  *
810  * The TPM circuit has a separate chip-select input but shares the clock and
811  * data pins of the rest of the spi_device. The TPM can be enabled alongside
812  * the other data path (for generic/flash/passthrough modes).
813  *
814  * @param spi A handle to a spi device.
815  * @param enable Whether to enable the TPM block.
816  * @param config The TPM configuration.
817  * @return The result of the operation.
818  */
821  dif_toggle_t enable,
823 
825  /** True if a command and address have been captured and are can be read. */
827  /** True if the write FIFO is under software's exclusive use. */
829  /** True if the last command targeted the Read FIFO and was aborted. */
832 
833 /**
834  * Get the current status of the TPM's data FIFOs and command / address
835  * register.
836  *
837  * @param spi A handle to a spi device.
838  * @param[out] status The status of the TPM.
839  * @return The result of the operation.
840  */
844 
845 /**
846  * Set the value for the TPM_ACCESS_x register, for use when the
847  * return-by-hardware mode is active for this register type.
848  *
849  * @param spi A handle to a spi device.
850  * @param locality Which TPM_ACCESS_x register to target, indexed by the
851  * locality.
852  * @param value The value to set the TPM_ACCESS_x register to.
853  * @return The result of the operation.
854  */
857  uint8_t locality, uint8_t value);
858 
859 /**
860  * Get the value of the TPM_ACCESS_x register that is used when the
861  * return-by-hardware mode is active for this register type.
862  *
863  * @param spi A handle to a spi device.
864  * @param locality Which TPM_ACCESS_x register to query, indexed by the
865  * locality.
866  * @param[out] value The value of the TPM_ACCESS_x register.
867  * @return The result of the operation.
868  */
871  uint8_t locality,
872  uint8_t *value);
873 
874 /**
875  * Set the value for the TPM_STS register, for use when the
876  * return-by-hardware mode is active for this register type.
877  *
878  * @param spi A handle to a spi device.
879  * @param value The value to set the TPM_STS register to.
880  * @return The result of the operation.
881  */
884  uint32_t value);
885 
886 /**
887  * Get the value of the TPM_STS register that is used when the
888  * return-by-hardware mode is active for this register type.
889  *
890  * @param spi A handle to a spi device.
891  * @param[out] value The value of the TPM_STS register.
892  * @return The result of the operation.
893  */
896  uint32_t *value);
897 
898 /**
899  * Set the value for the TPM_INTF_CAPABILITY register, for use when the
900  * return-by-hardware mode is active for this register type.
901  *
902  * @param spi A handle to a spi device.
903  * @param value The value to set the TPM_INTF_CAPABILITY register to.
904  * @return The result of the operation.
905  */
908  dif_spi_device_handle_t *spi, uint32_t value);
909 
910 /**
911  * Get the value of the TPM_INTF_CAPABILITY register that is used when the
912  * return-by-hardware mode is active for this register type.
913  *
914  * @param spi A handle to a spi device.
915  * @param[out] value The value of the TPM_INTF_CAPABILITY register.
916  * @return The result of the operation.
917  */
920  dif_spi_device_handle_t *spi, uint32_t *value);
921 
922 /**
923  * Set the value for the TPM_INT_ENABLE register, for use when the
924  * return-by-hardware mode is active for this register type.
925  *
926  * @param spi A handle to a spi device.
927  * @param value The value to set the TPM_INT_ENABLE register to.
928  * @return The result of the operation.
929  */
932  uint32_t value);
933 
934 /**
935  * Get the value of the TPM_INT_ENABLE register that is used when the
936  * return-by-hardware mode is active for this register type.
937  *
938  * @param spi A handle to a spi device.
939  * @param[out] value The value of the TPM_INT_ENABLE register.
940  * @return The result of the operation.
941  */
944  uint32_t *value);
945 
946 /**
947  * Set the value for the TPM_INT_VECTOR register, for use when the
948  * return-by-hardware mode is active for this register type.
949  *
950  * @param spi A handle to a spi device.
951  * @param value The value to set the TPM_INT_VECTOR register to.
952  * @return The result of the operation.
953  */
956  uint32_t value);
957 
958 /**
959  * Get the value of the TPM_INT_VECTOR register that is used when the
960  * return-by-hardware mode is active for this register type.
961  *
962  * @param spi A handle to a spi device.
963  * @param[out] value The value of the TPM_INT_VECTOR register.
964  * @return The result of the operation.
965  */
968  uint32_t *value);
969 
970 /**
971  * Set the value for the TPM_INT_STATUS register, for use when the
972  * return-by-hardware mode is active for this register type.
973  *
974  * @param spi A handle to a spi device.
975  * @param value The value to set the TPM_INT_STATUS register to.
976  * @return The result of the operation.
977  */
980  uint32_t value);
981 
982 /**
983  * Get the value of the TPM_INT_STATUS register that is used when the
984  * return-by-hardware mode is active for this register type.
985  *
986  * @param spi A handle to a spi device.
987  * @param value[out] The value of the TPM_INT_STATUS register.
988  * @return The result of the operation.
989  */
992  uint32_t *value);
993 
994 typedef struct dif_spi_device_tpm_id {
995  /** The vendor ID found in the TPM_DID_VID register. */
996  uint16_t vendor_id;
997  /** The device ID found in the TPM_DID_VID register. */
998  uint16_t device_id;
999  /** The revision ID found in the TPM_RID register. */
1000  uint8_t revision;
1002 
1003 /**
1004  * Set the values for the TPM_DID_VID and TPM_RID registers, for use when the
1005  * return-by-hardware mode is active for this register type.
1006  *
1007  * @param spi A handle to a spi device.
1008  * @param id The values to set the registers to.
1009  * @return The result of the operation.
1010  */
1014 
1015 /**
1016  * Get the values of the TPM_DID_VID and TPM_RID registers that are used when
1017  * the return-by-hardware mode is active for this register type.
1018  *
1019  * @param spi A handle to a spi device.
1020  * @param[out] value The value of the registers.
1021  * @return The result of the operation.
1022  */
1025  dif_spi_device_tpm_id_t *value);
1026 
1027 /**
1028  * Retrieve the command and address of the current command.
1029  *
1030  * @param spi A handle to a spi device.
1031  * @param[out] command The command opcode.
1032  * @param[out] address The address associated with the command.
1033  * @return The result of the operation.
1034  */
1037  uint8_t *command,
1038  uint32_t *address);
1039 
1040 /**
1041  * Write data to the TPM's ReadFIFO.
1042  *
1043  * @param spi A handle to a spi device.
1044  * @param length The length, in bytes, of the data to be copied.
1045  * @param buf A pointer to the location of the data to be copied.
1046  * @return The result of the operation.
1047  */
1050  size_t length, uint8_t *buf);
1051 
1052 /**
1053  * Read data from the TPM's WriteFIFO.
1054  *
1055  * @param spi A handle to a spi device.
1056  * @param length The length, in bytes, of the data to be copied.
1057  * @param[out] buf A pointer to the location where the data should be stored.
1058  * @return The result of the operation.
1059  */
1062  size_t length, uint8_t *buf);
1063 
1064 /**
1065  * Release the TPM's WriteFIFO back to hardware.
1066  *
1067  * @param spi A handle to a spi device.
1068  * @return The result of the operation.
1069  */
1072 
1073 #ifdef __cplusplus
1074 } // extern "C"
1075 #endif // __cplusplus
1076 
1077 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_SPI_DEVICE_H_