sys/man/3/flash

   1 .TH FLASH 3
   2 .SH NAME
   3 flash \- flash memory
   4 .SH SYNOPSYS
   5 .nf
   6 .BI "bind -a #F" \fR[\fPn\fR]\fP " /dev"
   7 .sp 0.3v
   8 .B /dev/flash
   9 .BI /dev/flash/ part
  10 .BI /dev/flash/ part ctl
  11 .fi
  12 .SH DESCRIPTION
  13 The flash memory device serves a two-level directory,
  14 giving access to files representing part or all of a bank of flash memory.
  15 A platform might have more than one bank of flash, numbered starting from 0.
  16 The attach specifier
  17 .I n
  18 is a decimal integer that selects a particular bank of flash (default: 0).
  19 Both NOR and NAND flash is supported.
  20 For both types of flash,
  21 the driver gives a read/write/erase interface to the raw flash device,
  22 which can impose constraints on operations beyond those imposed by the driver.
  23 Other drivers such as
  24 .IR ftl (3)
  25 or
  26 .IR logfs (3)
  27 implement any higher-level format required,
  28 including ECC for NAND flash, for instance.
  29 .PP
  30 The top level directory contains a single directory named
  31 .B flash
  32 for bank 0, and
  33 .BI flash n
  34 for each other bank
  35 .IR n .
  36 It contains two files for each partition:
  37 a data file
  38 .I part
  39 and an associated control file
  40 .IB part ctl ,
  41 where
  42 .I part
  43 is the name of the partition.
  44 Each partition represents a region of flash memory that starts and ends
  45 on a flash segment (erase unit) boundary.
  46 The system initially creates a single standard partition
  47 .B flash
  48 representing the whole of flash memory, and the corresponding control file
  49 .BR flashctl .
  50 Other partitions can be created by writing to
  51 .B flashctl
  52 as described below.
  53 .PP
  54 The data file
  55 .I part
  56 provides read and write access to the bytes on the system's flash memory.
  57 Bytes can be read and written on any byte boundary:
  58 the interface hides any alignment restrictions.
  59 A read returns the value of the bytes at the current file offset,
  60 where zero is the start of the partition.
  61 A write reprograms the flash to the given byte values, at the current
  62 file offset (relative to the start of the partition), using the physical
  63 device's reprogramming algorithm.
  64 An erased flash byte is logically
  65 .B 0xFF
  66 (regardless of the conventions of the physical flash device).
  67 A write can change a bit with value 1 to a 0,
  68 but cannot change a 0 bit to 1;
  69 that can only be done by erasing one or more flash segments.
  70 NAND flash typically has restrictions on the number of writes
  71 allowed to a page before requiring a block erase.
  72 .\" bad idea:
  73 .\" Reads and writes are unbuffered.
  74 .PP
  75 The control file
  76 .BI part ctl
  77 can be read and written.
  78 A read returns several lines containing decimal and hexadecimal numbers
  79 (separated by white space)
  80 revealing the characteristics of memory within the partition.
  81 The first line gives the
  82 the manufacturer ID,  the flash device ID, the memory width in bytes,
  83 and a string giving the flash type
  84 (currently either
  85 .B nor
  86 or
  87 .BR nand ).
  88 Subsequent lines give characteristics of each group of erase units
  89 within the partition,
  90 where the erase units within a group have the same properties.
  91 Each line gives the start and end (as byte addresses)
  92 of the erase units in the region
  93 that lie within the partition,
  94 followed by the size in bytes of each erase unit, which is followed
  95 for NAND flash by the size in bytes of a page.
  96 The sizes for NAND flash include the extra bytes per page
  97 typically used to hold an ECC and block status.
  98 A write contains one of the following textual commands:
  99 .TF "erase al"
 100 .TP
 101 .BI add " name start end"
 102 Create a new partition that ranges from
 103 .I start
 104 to
 105 .I end
 106 within the current partition.
 107 Each value must be numeric (decimal, octal or hexadecimal)
 108 and a multiple of the erase unit size.
 109 .I Name
 110 must not be the name of an existing partition.
 111 On success, new files
 112 .I name
 113 and
 114 .IB name ctl
 115 will appear in the parent
 116 .B flash
 117 directory.
 118 .TP
 119 .B erase all
 120 Erase the whole flash partition, setting all bytes to
 121 .BR 0xFF ,
 122 except those that are hardware write-protected.
 123 .TP
 124 .BI erase " offset"
 125 Erase the segment that begins at the given
 126 .I offset
 127 within the partition,
 128 setting all bytes to
 129 .BR 0xFF ,
 130 except those that are hardware write-protected.
 131 The
 132 .I offset
 133 is given in bytes, but must be a multiple
 134 of the segment (erase unit) size.
 135 .TP
 136 .BR protectboot " [ " off " ]"
 137 By default the system prevents erase unit 0 of the flash from being
 138 erased or written, assuming it
 139 contains the primary bootstrap.
 140 Writing this command with parameter
 141 .B off
 142 removes that protection.
 143 Writing
 144 .B protectboot
 145 with any other parameter (or none) restores the protection.
 146 Note that a manufacturer might also have locked the flash in hardware,
 147 and that protection must be removed in a device-dependent way.
 148 .TP
 149 .B sync
 150 If the underlying device must buffer or cache (current devices do not),
 151 flush the buffer(s).
 152 .PD
 153 .PP
 154 The syntax of all numbers is that of
 155 .I strtoul
 156 (in
 157 .IR atof (2));
 158 the default base is 10.
 159 .SH SOURCE
 160 .B /sys/src/*/devflash.c
 161 .br
 162 .B /sys/src/*/flash*.c
 163 .SH SEE ALSO
 164 .IR flashfs (4),
 165 .IR paqfs (4)
 166 .SH DIAGNOSTICS
 167 A write will return an error if
 168 an attempt is made to change a 0 bit to 1,
 169 or if the flash memory fails to be programmed correctly.
 170 .SH BUGS
 171 The flash cannot be written if the kernel is executing directly from flash,
 172 because the physical flash cannot be read during programming,
 173 and the driver does not copy the programming code to DRAM.