1) Rather the commit this my self, I'd like somebody to read through the
comments (double check my work), much of this is by just reading the
source code and entering doxygen text.
2) Well call it "doxygen style", sure looks like doxygen, but it is not
picking up the field documentation correctly. But hey, at least it's
comments, a step in the right direction!.
-Duane.
Index: openocd.head/src/flash/flash.h
===================================================================
--- openocd.head/src/flash/flash.h (revision 1858)
+++ openocd.head/src/flash/flash.h (working copy)
@@ -33,50 +33,195 @@
#define FLASH_MAX_ERROR_STR (128)
+/** Flash sector (within a flash bank) */
typedef struct flash_sector_s
{
+ /* Offset, in bytes from start of this flash chip
+ * This 'offset' is the bus offset, hence 4 chips (8bit) on a 32bit bus
+ * each byte is a
+ */
u32 offset;
+
+ /* size, in bytes of this flash chip */
u32 size;
+
+ /* 0=not erased,
+ * 1=erased,
+ * other=unknown
+ * Set by various blank checks routines.
+ */
int is_erased;
+
+ /* 0=unprotected(unlocked)
+ * 1=protected(locked)
+ * other=unknown
+ */
int is_protected;
} flash_sector_t;
struct flash_bank_s;
+/** Flash Driver Structure. */
typedef struct flash_driver_s
{
+ /** The name of this flash type
+ *
+ * The user gives the command:
+ * \code
+ * flash bank DRIVERNAME ...parameters...
+ * \endcode
+ *
+ * This <b>name</b> is used select and initialie the driver.
+
+ */
char *name;
+
+ /** Create this flash chip specific commands.
+ *
+ * Called during the "flash bank" command described above.
+ * SUCCCESS: return ERROR_OK
+ * Otherwise: return some error
+ *
+ */
int (*register_commands)(struct command_context_s *cmd_ctx);
+
+ /** finish the "flash bank" command for this flash chip.
+ *
+ * \param cmd_ctx - the command context
+ * \param cmd - the command, in this case 'flash'
+ * \param args - parameters, see below
+ * \param argc - number of parameters on command line
+ * \param bank - new filled in flash bank.
+ *
+ * The args are:
+ * \code
+ * argv[0] = bank
+ * argv[1] = drivername {name above}
+ * argv[2] = baseaddress
+ * argv[3] = lengthbytes
+ * argv[4] = chip_width_in bytes
+ * argv[5] = bus_width_bytes
+ * argv[6] = begin the "target specific parameters"
+ * \endcode
+ *
+ * Example: [4] = 16 bit flash, [5] on a 32bit bus
+ *
+ * Driver specific items start at [6].
+ *
+ * The bank parameter is filled in by the 'flash core' code
+ * driver can store 'private' info in 'flash_bank_t::driver_priv'
+ */
int (*flash_bank_command)(struct command_context_s *cmd_ctx, char *cmd,
char **args, int argc, struct flash_bank_s *bank);
- /* use flash_driver_erase() wrapper to invoke */
- int (*erase)(struct flash_bank_s *bank, int first, int last);
+ /** target specific erase routine.
+ * \param bank - the bank to erase
+ * \param first_sector - typically 0
+ * \param num_sectors - typically N-1
+ *
+ * Driver should erase the specified sectors.
+ */
+ int (*erase)(struct flash_bank_s *bank, int first_sector, int
num_sectors );
- /* use flash_driver_protect() wrapper to invoke */
+ /** target specific protect routine
+ * \param bank - the bank to protect
+ * \param set - 0 (disable protection), (!0) enable protection
+ * \param first_sector - first sector to protect, typicaly 0
+ * \param nsectors - typically (N-1)
+ *
+ * This should turn on any 'flash write or erase protection bits'
+ */
int (*protect)(struct flash_bank_s *bank, int set, int first, int last);
- /* use the flash_driver_write() wrapper to invoke. */
+ /** Write (ie: Program) the flash
+ * \param bank - the bank to program
+ * \param buffer - the data bytes to write.
+ * \param offset - the offset into the chip to program.
+ * \param count - count, in bytes to write.
+ *
+ * Note CPU address is : "bank->base + offset" The physical
+ * address is dependent upon current target MMU mappings.
+ */
int (*write)(struct flash_bank_s *bank, u8 *buffer, u32 offset, u32
count);
+ /** Probe, attempt to determine if the flash is actually present.
+ * \param bank - the bank to probe
+ *
+ * This is invoked by the "probe" command.
+ */
int (*probe)(struct flash_bank_s *bank);
+
+ /** Blank(erase) check a flash bank.
+ * \param bank - the bank to check
+ * This routine must set/clear:
+ * bank->sectors[ all ].is_erased
+ * to 0 if not erased
+ * to 1 if erased
+ * to (other) if state is unknown.
+ */
int (*erase_check)(struct flash_bank_s *bank);
+
+ /** Determine if the specific bank is "protected" or not
+ * For each "sector" the driver must set:
+ * bank->sectors[ N ].is_protected
+ * to 1 if it is protected
+ * to 0 if it is not protected.
+ */
int (*protect_check)(struct flash_bank_s *bank);
+
+ /** Print human information about the flash bank into the given buffer.
+ * Do not overflow the buffer.
+ * \param bank - the bank to get info about
+ * \param char - where to put the text for the human to read
+ * \param buf_size - the size of the human buffer.
+ */
int (*info)(struct flash_bank_s *bank, char *buf, int buf_size);
+
+ /* Probe - in a not very noisy manner.
+ * \param bank - the bank to probe
+ *
+ * Generally, this code should test if the bank has already been probed.
+ * if it has, do not probe again.
+ *
+ * This is often called from the inside of other routines (for example:
+ * GDB flash downloads) to autoprobe the flash as it is programing the
flash
+ */
int (*auto_probe)(struct flash_bank_s *bank);
} flash_driver_t;
+/** A flash 'bank' - aka: chip or major flash block. */
typedef struct flash_bank_s
{
+ /* The target this flash bank belongs to. */
struct target_s *target;
+ /* the driver for this flash bank. */
flash_driver_t *driver;
+
+ /* For use by the driver */
void *driver_priv;
+
+ /* Which 'bank' or chip number this is */
int bank_number;
+
+ /* base address of this chip */
u32 base;
+
+ /* what size (in bytes) is this chip */
u32 size;
+
+ /* Width of the chip in bytes (1,2,4 bytes)*/
int chip_width;
+ /* Max bus width in bytes (1,2,4 bytes) */
int bus_width;
+
+ /* how many sectors on this chip, initially 0 the "flash driver"
+ * must set this to some non-zero value. during "probe()" or
+ * "auto_probe()"
+ */
int num_sectors;
+ /* Array of sectors, allocated and initilized by the flash driver */
flash_sector_t *sectors;
+
+ /* next flash bank on this chip */
struct flash_bank_s *next;
} flash_bank_t;
_______________________________________________
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
