strata-instance.html

ecos3.0 beta 的官方文档,html格式

><P
>The bulk of the file is protected by an ifdef for the Strata flash
driver. That driver will only be active if the generic flash support
is enabled. Without that support there will be no way of accessing
the device so there is no point in instantiating the device. The rest
of the file is split into three definitions. The first supplies the
functions which will be used to perform the actual flash accesses,
using a macro provided by the generic flash code in <TT
CLASS="FILENAME"
>cyg/io/flash_dev.h</TT
>. The
relevant ones have an <TT
CLASS="LITERAL"
>_16</TT
> suffix, indicating that
on this board there is a single 16-bit flash device on a 16-bit
bus. The second definition provides information specific to Strata
flash devices. The third provides the
<CODE
CLASS="STRUCTNAME"
>cyg_flash_dev</CODE
> structure needed by the generic
flash code, which contains pointers to the previous two.
    </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="STRATA-INSTANCE-FUNCTIONS"
></A
><H2
>Functions</H2
><P
>All eCos flash device drivers must implement a standard interface,
defined by the generic flash code <CODE
CLASS="VARNAME"
>CYGPKG_IO_FLASH</CODE
>.
This interface includes a table of 7 function pointers for various
operations: initialization, query, erase, program, read,
locking and unlocking. The query operation is optional and
the generic flash support provides a dummy implementation
<CODE
CLASS="FUNCTION"
>cyg_flash_devfn_query_nop</CODE
>. Strata flash devices
are always directly accessible so there is no need for a separate read
function. The remaining functions are more complicated.
    </P
><P
>Usually the table can be declared <TT
CLASS="LITERAL"
>const</TT
>. In a ROM
startup application this avoids both ROM and RAM copies of the table,
saving a small amount of memory. <TT
CLASS="LITERAL"
>const</TT
> should not
be used if the table may be modified by a platform-specific
initialization routine.
    </P
><DIV
CLASS="REFSECT2"
><A
NAME="STRATA-INSTANCE-FUNCTIONS-INIT"
></A
><H3
>Initialization</H3
><P
>There is a choice of three main initialization functions. The simplest
is <CODE
CLASS="FUNCTION"
>cyg_flash_devfn_init_nop</CODE
>, which does nothing. It
can be used if the <CODE
CLASS="STRUCTNAME"
>cyg_strata_dev</CODE
> and
<CODE
CLASS="STRUCTNAME"
>cyg_flash_dev</CODE
> structures are fully
initialized statically and the flash will just work without special
effort. This is useful if it is guaranteed that the board will always
be manufactured using the same flash chip, since the nop function
involves the smallest code size and run-time overheads.
      </P
><P
>The next step up is
<CODE
CLASS="FUNCTION"
>cyg_strata_init_check_devid_XX</CODE
>, where
<TT
CLASS="LITERAL"
>XX</TT
> will be replaced by the suffix appropriate for
the bus configuration. It is still necessary to provide all the device
information statically, including the <CODE
CLASS="STRUCTFIELD"
>devid</CODE
>
field in the <CODE
CLASS="STRUCTNAME"
>cyg_strata_dev</CODE
> structure.
However this initialization function will attempt to query the flash
device and check that the provided manufacturer and device codes
matches the actual hardware. If there is a mismatch the device will be
marked uninitialized and subsequent attempts to manipulate the flash
will fail.
      </P
><P
>If the board may end up being manufactured with any of a number of
different flash chips then the driver can perform run-time
initialization, using a <CODE
CLASS="FUNCTION"
>cyg_strata_init_cfi_XX</CODE
>
function. This queries the flash device as per the Common Flash Memory
Interface Specification, supported by all current devices (although
not necessarily by older devices). The
<CODE
CLASS="STRUCTFIELD"
>block_info</CODE
> field in the
<CODE
CLASS="STRUCTNAME"
>cyg_strata_dev</CODE
> structure and the
<CODE
CLASS="STRUCTFIELD"
>end</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>num_block_infos</CODE
> fields in the
<CODE
CLASS="STRUCTNAME"
>cyg_flash_dev</CODE
> structure will be filled in.
It is still necessary to supply the <CODE
CLASS="STRUCTFIELD"
>start</CODE
>
field statically since otherwise the driver will not know how to
access the flash device. The main disadvantage of using CFI is that it
will increase the code size.
      </P
><P
>A final option is to use a platform-specific initialization function.
This may be useful if the board may be manufactured with one of a
small number of different flash devices and the platform HAL needs to
adapt to this. The Strata driver provides a utility function to
read the device id, <A
HREF="strata-api-other.html"
><CODE
CLASS="FUNCTION"
>cyg_strata_read_devid_XX</CODE
></A
>: 
      </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static int
kikoo_flash_init(struct cyg_flash_dev* dev)
{
    int manufacturer_code, device_code;
    cyg_strata_read_devid_1616(dev, &amp;manufacturer_code, &amp;device_code);
    if (manufacturer_code != CYG_FLASH_STRATA_MANUFACTURER_STMICRO) {
        return CYG_FLASH_ERR_DRV_WRONG_PART;
    }
    switch(device_code) {
        case 0x0042 :
          &#8230;
        case 0x0084 :
          &#8230;
        default:
          return CYG_FLASH_ERR_DRV_WRONG_PART;
    }
}
      </PRE
></TD
></TR
></TABLE
><P
>There are many other possible uses for a platform-specific
initialization function. For example initial prototype boards might
have only supported 8-bit access to a 16-bit flash device rather than
16-bit access, but this was fixed in the next revision. The
platform-specific initialization function could figure out which model
board it is running on and replace the default
<TT
CLASS="LITERAL"
>16as8</TT
> functions with <TT
CLASS="LITERAL"
>16</TT
> ones.
      </P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="STRATA-INSTANCE-FUNCTIONS-ERASE-PROGRAM"
></A
><H3
>Erase and Program</H3
><P
>The Strata driver provides erase and program functions appropriate
for the various bus configurations. On most targets these can be used
directly. On some targets it may be necessary to do some extra work
before and after the erase and program operations. For example if the
hardware has an MMU then the part of the address map containing the
flash may have been set to read-only, in an attempt to catch spurious
memory accesses. Erasing or programming the flash requires
write-access, so the MMU settings have to be changed temporarily. For
another example some flash device may require a higher voltage to be
applied during an erase or program operation. or a higher voltage may
be desirable to make the operation proceed faster. A typical
platform-specific erase function would look like this:
      </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static int
kikoo_flash_erase(struct cyg_flash_dev* dev, cyg_flashaddr_t addr)
{
    int result;
    &#8230;  // Set up the hardware for an erase
    result = cyg_strata_erase_32(dev, addr);
    &#8230;  // Revert the hardware change
    return result;
}
      </PRE
></TD
></TR
></TABLE
><P
>There are two versions of the program function.
<CODE
CLASS="FUNCTION"
>cyg_strata_bufprogram_xx</CODE
> uses the buffered write
capability of some strata chips. This allows the flash chip to perform
the writes in parallel, thus greatly improving performance. It
requires that the <CODE
CLASS="STRUCTFIELD"
>bufsize</CODE
> field of the
<CODE
CLASS="STRUCTNAME"
>cyg_strata_dev</CODE
> structure is set correctly to
the number of words in the write buffer. The usual value for this is
16, corresponding to a 32-byte write buffer. The alternative
<CODE
CLASS="FUNCTION"
>cyg_strata_program_xx</CODE
> writes the data one word at
a time so is significantly slower. It should be used only with strata
chips that do not support buffered writes, for example the b3 and c3
series.
      </P
><P
>There are two configuration options which affect the erase and program
functions, and which a platform HAL may wish to change:
<CODE
CLASS="VARNAME"
>CYGNUM_DEVS_FLASH_STRATA_V2_ERASE_TIMEOUT</CODE
> and
<CODE
CLASS="VARNAME"
>CYGNUM_DEVS_FLASH_STRATA_V2_PROGRAM_TIMEOUT</CODE
>. The
erase and program operations both involve polling for completion, and
these timeout impose an upper bound on the polling loop. Normally
these operations should never take anywhere close to the timeout
period, and hence a timeout probably indicates a catastrophic failure
that should really be handled by a watchdog reset. A reset is
particularly appropriate because there will be no clean way of
aborting the flash operation. The main reason for the timeouts is to
help with debugging when porting to new hardware. If there is a valid
reason why a particular platform needs different timeouts then the
platform HAL's CDL can require appropriate values for these options.
      </P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="STRATA-INSTANCE-FUNCTIONS-LOCKING"
></A
><H3
>Locking</H3
><P
>Current Strata devices implement locking in three different ways,
requiring different sets of functions:
      </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>28FxxxB3</DT
><DD
><P
>There is no software locking support. The
<CODE
CLASS="FUNCTION"
>cyg_flash_devfn_lock_nop</CODE
> and
<CODE
CLASS="FUNCTION"
>cyg_flash_devfn_unlock_nop</CODE
> functions should be used.
          </P
></DD
><DT
>28FxxxC3, 28FxxxK3</DT
><DD
><P
>These support locking and unlocking individual blocks. The
<CODE
CLASS="FUNCTION"
>cyg_strata_lock_k3_XX</CODE
> and
<CODE
CLASS="FUNCTION"
>cyg_strata_unlock_k3_XX</CODE
> functions should be used.
All blocks are locked following power-up or reset, so the unlock
function must be used before any erase or program operation.
Theoretically the lock function is optional and
<CODE
CLASS="FUNCTION"
>cyg_flash_devfn_lock_nop</CODE
> can be used instead, saving a
small amount of code space.
          </P
></DD
><DT
>28FxxxJ3</DT
><DD
><P
>Individual blocks can be locked using
<CODE
CLASS="FUNCTION"
>cyg_strata_lock_j3_XX</CODE
>, albeit using a slightly
different algorithm from the C3 and K3 series. However the only unlock
support is a global unlock of all blocks. Hence the only way to unlock
a single block is to check the locked status of every block, unlock
them all, and relock the ones that should still be locked. This
time-consuming operation is implemented by
<CODE
CLASS="FUNCTION"
>cyg_strata_unlock_j3_XX</CODE
>. Worse, unlocking all
blocks can take approximately a second. During this time the flash is
unusable so normally interrupts have to be disabled, affecting
real-time responsiveness. There is no way of suspending this
operation.
          </P
><P
>Unlike the C3 and K3 chips, on a J3 blocks are not automatically
locked following power-up or reset. Hence lock and unlock support is
optional, and <CODE
CLASS="FUNCTION"
>cyg_flash_devfn_lock_nop</CODE
> and
<CODE
CLASS="FUNCTION"
>cyg_flash_devfn_unlock_nop</CODE
> can be used.
          </P
></DD
></DL
></DIV
><P
>If real locking functions are used then the platform HAL's CDL script
should implement the CDL interface
<CODE
CLASS="VARNAME"
>CYGHWR_IO_FLASH_BLOCK_LOCKING</CODE
>. Otherwise the
generic flash package may believe that none of the flash drivers in
the system provide locking functionality and disable the interface
functions.
      </P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="STRATA-INSTANCE-DEVPRIV"
></A
><H2
>Device-Specific Structure</H2
><P
>The <CODE
CLASS="STRUCTNAME"
>cyg_strata_dev</CODE
> structure provides
information specific to Strata flash devices, as opposed to the
more generic flash information which goes into the
<CODE
CLASS="STRUCTNAME"
>cyg_flash_dev</CODE
> structure. There are only two
fields: <CODE
CLASS="STRUCTFIELD"
>devid</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>block_info</CODE
>.
    </P
><P
><CODE
CLASS="STRUCTFIELD"
>manufacturer_code</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>device_code</CODE
> are needed only if the driver's
initialization function is set to
<CODE
CLASS="FUNCTION"
>cyg_strata_init_check_devid_XX</CODE
>. That function
will extract the actual device info from the flash chip and compare it
with these fields. If there is a mismatch then subsequent operations
on the device will fail. Definitions of
<CODE
CLASS="VARNAME"
>CYG_FLASH_STRATA_MANUFACTURER_INTEL</CODE
> and
<CODE
CLASS="VARNAME"
>CYG_FLASH_STRATA_MANUFACTURER_STMICRO</CODE
> are provided
for convenience.
    </P
><P
>The <CODE
CLASS="STRUCTFIELD"
>bufsize</CODE
> field is needed only if a
buffered program function
<CODE
CLASS="FUNCTION"
>cyg_strata_bufprogram_XX</CODE
> is used. It should give
the size of the buffer in words. Typically Strata devices have a
32-byte buffer, so when attached to an 8-bit bus
<CODE
CLASS="STRUCTFIELD"
>bufsize</CODE
> should be 32 and when attached to a