1/**
2 * \file libyasm/listfmt.h
3 * \brief YASM list format interface.
4 *
5 * \license
6 *  Copyright (C) 2004-2007  Peter Johnson
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *  - Redistributions of source code must retain the above copyright
12 *    notice, this list of conditions and the following disclaimer.
13 *  - Redistributions in binary form must reproduce the above copyright
14 *    notice, this list of conditions and the following disclaimer in the
15 *    documentation and/or other materials provided with the distribution.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND OTHER CONTRIBUTORS ``AS IS''
18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR OTHER CONTRIBUTORS BE
21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 * POSSIBILITY OF SUCH DAMAGE.
28 * \endlicense
29 */
30#ifndef YASM_LISTFMT_H
31#define YASM_LISTFMT_H
32
33#ifndef YASM_DOXYGEN
34/** Base #yasm_listfmt structure.  Must be present as the first element in any
35 * #yasm_listfmt implementation.
36 */
37typedef struct yasm_listfmt_base {
38    /** #yasm_listfmt_module implementation for this list format. */
39    const struct yasm_listfmt_module *module;
40} yasm_listfmt_base;
41#endif
42
43/** YASM list format module interface. */
44typedef struct yasm_listfmt_module {
45    /** One-line description of the list format. */
46    const char *name;
47
48    /** Keyword used to select list format. */
49    const char *keyword;
50
51    /** Create list format.
52     * Module-level implementation of yasm_listfmt_create().
53     * The filenames are provided solely for informational purposes.
54     * \param in_filename   primary input filename
55     * \param obj_filename  object filename
56     * \return NULL if unable to initialize.
57     */
58    /*@null@*/ /*@only@*/ yasm_listfmt * (*create)
59        (const char *in_filename, const char *obj_filename);
60
61    /** Module-level implementation of yasm_listfmt_destroy().
62     * Call yasm_listfmt_destroy() instead of calling this function.
63     */
64    void (*destroy) (/*@only@*/ yasm_listfmt *listfmt);
65
66    /** Module-level implementation of yasm_listfmt_output().
67     * Call yasm_listfmt_output() instead of calling this function.
68     */
69    void (*output) (yasm_listfmt *listfmt, FILE *f, yasm_linemap *linemap,
70                    yasm_arch *arch);
71} yasm_listfmt_module;
72
73/** Get the keyword used to select a list format.
74 * \param listfmt   list format
75 * \return keyword
76 */
77const char *yasm_listfmt_keyword(const yasm_listfmt *listfmt);
78
79/** Initialize list format for use.  Must call before any other list
80 * format functions.  The filenames are provided solely for informational
81 * purposes.
82 * \param module        list format module
83 * \param in_filename   primary input filename
84 * \param obj_filename  object filename
85 * \return NULL if object format does not provide needed support.
86 */
87/*@null@*/ /*@only@*/ yasm_listfmt *yasm_listfmt_create
88    (const yasm_listfmt_module *module, const char *in_filename,
89     const char *obj_filename);
90
91/** Cleans up any allocated list format memory.
92 * \param listfmt       list format
93 */
94void yasm_listfmt_destroy(/*@only@*/ yasm_listfmt *listfmt);
95
96/** Write out list to the list file.
97 * This function may call all read-only yasm_* functions as necessary.
98 * \param listfmt       list format
99 * \param f             output list file
100 * \param linemap       line mapping repository
101 * \param arch          architecture
102 */
103void yasm_listfmt_output(yasm_listfmt *listfmt, FILE *f,
104                         yasm_linemap *linemap, yasm_arch *arch);
105
106#ifndef YASM_DOXYGEN
107
108/* Inline macro implementations for listfmt functions */
109
110#define yasm_listfmt_keyword(listfmt) \
111    (((yasm_listfmt_base *)listfmt)->module->keyword)
112
113#define yasm_listfmt_create(module, in_filename, obj_filename) \
114    module->create(in_filename, obj_filename)
115
116#define yasm_listfmt_destroy(listfmt) \
117    ((yasm_listfmt_base *)listfmt)->module->destroy(listfmt)
118
119#define yasm_listfmt_output(listfmt, f, linemap, a) \
120    ((yasm_listfmt_base *)listfmt)->module->output(listfmt, f, linemap, a)
121
122#endif
123
124#endif
125