PARTITIONS: Update documentation
Change the documentation to reflect the removal of the option on
the erase functions, the addition of the partition_*pre/post
functions and add headers to provide some logical divisions of
the text.
Change-Id: I9f47199a4306b5666e626ca834889e44589213cf
Signed-off-by: Scott Anderson <[email protected]>
diff --git a/doc/README.partition_funcs b/doc/README.partition_funcs
index 669b1b1..cb90310 100644
--- a/doc/README.partition_funcs
+++ b/doc/README.partition_funcs
@@ -1,3 +1,5 @@
+OVERVIEW
+========
It is useful to be able to access partitions on block devices in a general
purpose fashion, however to do so can require device specific knowledge. For
example, some devices require erases before writes and some partitions need to
@@ -8,11 +10,10 @@
int get_partition_by_name(block_dev_desc_t *dev, const char *partition_name,
disk_partition_t *partition);
-enum erase_option { ERASE_BEFORE_WRITE, ERASE_ALWAYS };
int partition_erase_blks(block_dev_desc_t *dev, disk_partition_t *partition,
- lbaint_t *blkcnt, enum erase_option opt);
+ lbaint_t *blkcnt);
int partition_erase_bytes(block_dev_desc_t *dev, disk_partition_t *partition,
- loff_t *bytecnt, enum erase_option opt);
+ loff_t *bytecnt);
int partition_read_blks(block_dev_desc_t *dev, disk_partition_t *partition,
lbaint_t *blkcnt, void *buffer);
@@ -24,6 +25,9 @@
int partition_write_bytes(block_dev_desc_t *dev, disk_partition_t *partition,
loff_t *bytecnt, const void *buffer);
+
+PRE_ AND POST_ ENVIRONMENT VARIABLES
+====================================
To accomplish the partition dependent configuration, these functions will use
environment variables to specify what commands need to be executed before and
after the operation is performed. The names of the environment variables that
@@ -68,6 +72,9 @@
ECC will be set to use hardware ECC before the partition is written and then
set back to software ECC after the partition is written.
+
+ERASE BEFORE WRITE
+==================
It should be noted that whether or not an erase is done before a write is
controlled by the C preprocessor define CONFIG_ERASE_PARTITION_ALWAYS. If it
is defined in the board configuration file, the following sequence will be
@@ -80,3 +87,22 @@
Note that this means that if you need to set pre_erase and/or post_erase,
you'll probably need pre_write and post_write to contain those same commands.
+
+
+CALLING BLOCK FUNCTIONS DIRECTLY
+================================
+
+There are times where it is required to access portions of the partition
+instead of reading or writing the entire partition. For example, a header
+needs to be read to know how much of the partition needs to be read. To do
+this, the code should use the block_read or block_write function pointers
+within the struct block_dev_desc and wrap those with calls to execute the pre_
+and post_ environment variables. The following functions are provided for
+that purpose:
+
+int partition_erase_pre(disk_partition_t *ptn);
+int partition_erase_post(disk_partition_t *ptn);
+int partition_read_pre(disk_partition_t *ptn);
+int partition_read_post(disk_partition_t *ptn);
+int partition_write_pre(disk_partition_t *ptn);
+int partition_write_post(disk_partition_t *ptn);
