1  #ifndef BITFILE_H
  2  #define BITFILE_H
  3  
  4  /*************************************************************************
  5  *
  6  * bitfile - a library for reading and writing Xilinx bitfiles
  7  *
  8  * Copyright (C) 2007 John Kasunich (jmkasunich at fastmail dot fm)
  9  *
 10  **************************************************************************
 11  
 12  This program is free software; you can redistribute it and/or
 13  modify it under the terms of version 2 of the GNU General
 14  Public License as published by the Free Software Foundation.
 15  This library is distributed in the hope that it will be useful,
 16  but WITHOUT ANY WARRANTY; without even the implied warranty of
 17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 18  GNU General Public License for more details.
 19  
 20  You should have received a copy of the GNU General Public
 21  License along with this library; if not, write to the Free Software
 22  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 23  
 24  THE AUTHORS OF THIS LIBRARY ACCEPT ABSOLUTELY NO LIABILITY FOR
 25  ANY HARM OR LOSS RESULTING FROM ITS USE.  IT IS _EXTREMELY_ UNWISE
 26  TO RELY ON SOFTWARE ALONE FOR SAFETY.  Any machinery capable of
 27  harming persons must have provisions for completely removing power
 28  from all motors, etc, before persons enter any danger area.  All
 29  machinery must be designed to comply with local and national safety
 30  codes, and the authors of this software can not, and do not, take
 31  any responsibility for such compliance.
 32  
 33  This code was written as part of the EMC HAL project.  For more
 34  information, go to www.linuxcnc.org.
 35  
 36  **************************************************************************
 37  
 38  Info about Xilinx bitfiles:
 39  
 40  The format consists of several variable length chunks, preceded by what
 41  seems to be a constant header.
 42  
 43  Some details about the header hint that it might actually be a variable
 44  length and content field as well, but I haven't found any files that
 45  had different content there (I googled up some nearly ten year old files,
 46  and I also examined ones made with the latest toolset).  So these
 47  functions treat that header as a constant, and report any header that
 48  doesn't match the standard as "not a bitfile".  The code would allow
 49  that rule to be relaxed if needed later.
 50  
 51  After the header, each "chunk" consists of a one byte "tag", a two or
 52  four byte length, and "length" bytes of data (the body).
 53  
 54  In some chunks, the body is a zero terminated printable string.  In others
 55  it is a blob of binary data.  The file format doesn't care.
 56  
 57  Standard Xilinx files use 5 chunks: 'a' through 'd' are zero-terminated
 58  strings with information about the file.  'e' is a large binary blob
 59  with the actual bitstream in it.  Xilinx uses 2 byte lengths for chunks
 60  'a' thru 'd', and 4 bytes for chunk 'e'.  This library allows other
 61  chunks, and assume that all have 4 byte lengths, except 'a' thru 'd'.
 62  
 63  This library allows additional chunks to be added to the file.
 64  
 65  *************************************************************************/
 66  
 67  struct bitfile_chunk {
 68      char tag;
 69      int len;
 70      unsigned char *body;
 71  };
 72  
 73  #define BITFILE_MAXCHUNKS 50
 74  /* list of chunks that use 2 byte length values, all others are 4 byte */
 75  #define BITFILE_SMALLCHUNKS "abcd"
 76  #define BITFILE_HEADERLEN 13
 77  
 78  struct bitfile {
 79      char *filename;
 80      unsigned char header[BITFILE_HEADERLEN];
 81      int num_chunks;
 82      struct bitfile_chunk chunks[BITFILE_MAXCHUNKS];
 83  };
 84  
 85  /************************************************************************/
 86  
 87  /* 'bitfile_new' allocates a struct bitfile, initializes its header field
 88     with the defaule xilinx header, and initializes its chunks as empty.
 89     It returns a pointer to the resulting struct, or NULL on error.
 90  */
 91  struct bitfile *bitfile_new(void);
 92  
 93  
 94  /* 'bitfile_free' frees all memory associated with a struct bitfile,
 95     including the chunk bodies and the struct itself.  It assumes that
 96     the struct was create by a call to 'bitfile_new' or 'bitfile_read'.
 97  */
 98  void bitfile_free(struct bitfile *bf);
 99  
100  
101  /* 'bitfile_read' reads a bitfile from disk, parses the individual chunks,
102     and stores them in a struct bitfile in memory.  The struct and the chunk
103     bodies are malloc'ed, and can be conveniently freed by `bitfile_free`.
104     It returns a pointer to the new struct bitfile, or NULL on error.
105  */
106  struct bitfile *bitfile_read(char *fname);
107  
108  
109  /* 'bitfile_write' writes the contents of a caller supplied struct bitfile
110     to a specified file in standard bitfile format.  It returns zero on
111     success, or -1 on failure.  It will write the standard xilinx 'a'
112     through 'e' chunks first, and in order, even if they are not that way
113     in the structure, followed by any extra chunks in the order in which
114     they are encounterd.  (This is to ensure compatibility with other 
115     programs that read bitfiles - this library doesn't care about chunk
116     ordering, but other programs might.)
117  */
118  int bitfile_write(struct bitfile *bf, char *fname);
119  
120  
121  /* 'bitfile_add_chunk` adds a new chunk to a caller supplied struct bitfile.
122     The data is copied into a newly allocated block of memory, so the original
123     can be dynamic memory, static memory, or anything else.  Returns zero on
124     success, or -1 on error.
125  */
126  int bitfile_add_chunk(struct bitfile *bf, char tag, int len, unsigned char *data);
127  
128  
129  /* 'bitfile_find_chunk` searches a caller supplied struct bitfile for a
130     chunk whose tag matches 'tag', and returns a pointer to that chunk, or
131     NULL if no match is found.  If 'n' is zero, it will return the first
132     matching chunk, if 'n' is 1 it will return the second, etc.  Note that
133     normal bitfiles never have more than one chunk with any given tag, so
134     'n' should usually be zero.
135  */
136  struct bitfile_chunk *bitfile_find_chunk(struct bitfile *bf, char tag, int n);
137  
138  
139  /* 'bitfile_print_chunk' searches a caller supplied struct bitfile for a
140     chunk whose tag matches 'tag', and prints the body of that chunk as a
141     string, preceded by a caller supplied title.  If no match is found
142     it prints nothing.  This is handy for printing out the contents of
143     the standard Xilinx 'a' through 'd' fields, but will print binary
144     junk if invoked on the 'e' chunk (the actual bitstream), or any chunk
145     not containing a zero-terminated printable string.
146  */
147  void bitfile_print_chunk(struct bitfile *bf, char tag, char *title);
148  
149  
150  /* 'bitfile_validate_xilinx_info` verifies that the caller supplied
151     struct bitfile contains the minimum chunks to be a valid Xilinx
152     bitstream - 'a' through 'e'.  It returns 0 for a valid bitstream,
153     and -1 if any required chunk is missing.
154  */
155  int bitfile_validate_xilinx_info(struct bitfile *bf);
156  
157  
158  /* 'bitfile_print_xilinx_info` invokes `bitfile_print_chunk` to print
159     the standard Xilinx 'a' through 'd' chunks (design name, targeted part,
160     date, and time) in a easily readable format.  It also prints the
161     length of the 'e' chunk (the bitstream).
162  */
163  void bitfile_print_xilinx_info(struct bitfile *bf);
164  
165  #endif /* BITFILE_H */