pstore/ram: Add kern-doc for struct persistent_ram_zone
authorKees Cook <keescook@chromium.org>
Thu, 1 Nov 2018 22:11:47 +0000 (15:11 -0700)
committerKees Cook <keescook@chromium.org>
Tue, 4 Dec 2018 00:52:35 +0000 (16:52 -0800)
The struct persistent_ram_zone wasn't well documented. This adds kern-doc
for it.

Signed-off-by: Kees Cook <keescook@chromium.org>
fs/pstore/ram_core.c
include/linux/pstore_ram.h

index 6283073..3e9e3ba 100644 (file)
 #include <linux/vmalloc.h>
 #include <asm/page.h>
 
+/**
+ * struct persistent_ram_buffer - persistent circular RAM buffer
+ *
+ * @sig:
+ *     signature to indicate header (PERSISTENT_RAM_SIG xor PRZ-type value)
+ * @start:
+ *     offset into @data where the beginning of the stored bytes begin
+ * @size:
+ *     number of valid bytes stored in @data
+ */
 struct persistent_ram_buffer {
        uint32_t    sig;
        atomic_t    start;
index 6e94980..5d10ad5 100644 (file)
  * PRZ_FLAG_NO_LOCK is used. For all other cases, locking is required.
  */
 #define PRZ_FLAG_NO_LOCK       BIT(0)
+/*
+ * If a PRZ should only have a single-boot lifetime, this marks it as
+ * getting wiped after its contents get copied out after boot.
+ */
 #define PRZ_FLAG_ZAP_OLD       BIT(1)
 
 struct persistent_ram_buffer;
@@ -43,17 +47,53 @@ struct persistent_ram_ecc_info {
        uint16_t *par;
 };
 
+/**
+ * struct persistent_ram_zone - Details of a persistent RAM zone (PRZ)
+ *                              used as a pstore backend
+ *
+ * @paddr:     physical address of the mapped RAM area
+ * @size:      size of mapping
+ * @label:     unique name of this PRZ
+ * @flags:     holds PRZ_FLAGS_* bits
+ *
+ * @buffer_lock:
+ *     locks access to @buffer "size" bytes and "start" offset
+ * @buffer:
+ *     pointer to actual RAM area managed by this PRZ
+ * @buffer_size:
+ *     bytes in @buffer->data (not including any trailing ECC bytes)
+ *
+ * @par_buffer:
+ *     pointer into @buffer->data containing ECC bytes for @buffer->data
+ * @par_header:
+ *     pointer into @buffer->data containing ECC bytes for @buffer header
+ *     (i.e. all fields up to @data)
+ * @rs_decoder:
+ *     RSLIB instance for doing ECC calculations
+ * @corrected_bytes:
+ *     ECC corrected bytes accounting since boot
+ * @bad_blocks:
+ *     ECC uncorrectable bytes accounting since boot
+ * @ecc_info:
+ *     ECC configuration details
+ *
+ * @old_log:
+ *     saved copy of @buffer->data prior to most recent wipe
+ * @old_log_size:
+ *     bytes contained in @old_log
+ *
+ */
 struct persistent_ram_zone {
        phys_addr_t paddr;
        size_t size;
        void *vaddr;
        char *label;
-       struct persistent_ram_buffer *buffer;
-       size_t buffer_size;
        u32 flags;
+
        raw_spinlock_t buffer_lock;
+       struct persistent_ram_buffer *buffer;
+       size_t buffer_size;
 
-       /* ECC correction */
        char *par_buffer;
        char *par_header;
        struct rs_control *rs_decoder;