+ Logisim is open-source software. The source code is included in the src subdirectory of the distributed JAR file.
+
+
+ If you find Logisim useful, please let me know. Especially do this if you are an educational institution; the information will help me in gaining support for the work.
+
+
+
+
+
+ I welcome e-mails about Logisim, including bug reports, suggestions, and fixes. When you e-mail me, please remember that I have worked hard to produce Logisim without receiving any payment from you. If you want a right to complain about the software, then I would suggest shelling out the money for a competing program to Logisim. (I know of no open-source competitors that approach Logisim's feature set.) Nonetheless, I remain interested in continuing to improve Logisim, and your suggestions will be most welcome.
+
+
+ Copyright notice
+
+
+ Copyright (c) 2005, Carl Burch.
+
+
+ Logisim is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+
+
+ Logisim is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+
+ Acknowledgements
+
+
+ The source code to Logisim is primarily my own work; I must acknowledge my employers who fund my work as a professor, including this program: I started the program at Saint John's University (Collegeville, Minnesota, USA) in 2000-2004, and I have continued it at Hendrix College (Conway, Arkansas, USA) from 2004 to present. I am very grateful to these colleges for giving me the time and resources to work on this project. If only all colleges and universities had their act as together and cared as much about excellent teaching as these colleges do!
+
+
+ Some other people who have been particularly helpful:
+
+
+
Theldo Cruz Franqueira, Thanos Kakarountas, Ilia Lilov, Pablo Leal Ramos, and Uwe Zimmermann, who have contributed to translations packaged with Logisim. More information about the translations can be found on International Preferences page.
+
+
The Spring 2005 CS61C class at the University of California, Berkeley, which endured the beta versions of Logisim 2.0. These students put up with many bugs, and I am very appreciative for their patience and for their suggestions!
+
+
The Spring 2001 CSCI 150 classes at the College of Saint Benedict and Saint John's University, which used the most rudimentary versions of Logisim as it was being developed.
+
+
+
+ Several pieces of Logisim come from others' packages that Logisim uses; several of these pieces are distributed as part of Logisim.
+
+
+
+ Sun's Java API (obviously)
+
+
+ Sun's JavaHelp project
+
+
+ Provides the integrated help system from the Help menu.
+
+
+ MRJAdapter, from Steve Roy
+
+
+ Integration with the Macintosh OS X platform.
+
+
+ launch4j, from Grzegorz Kowalt
+
+
+ Allows distribution of Logisim as a Windows executable.
+
+
+ ColorPicker, from Jeremy Wood
+
+
+ Provides the color dialog box that pops up when configuring colors (as with the LED component).
+
+
+ JFontChooser, from Christos Bohoris
+
+
+ Provides the font selection dialog box that pops up when selecting font attributes (such as with the Label Font attribute of many components).
+
+
+ TableSorter, ascribed to Philip Milne, Brendon McLean, Dan van Enckevort, Parwinder Sekhon, and ouroborus@ouroborus.org
+
+
+ Provides the ability to sort the table in the Get Circuit Statistics dialog through clicking column headers.
+
+ Provides the icons for controlling simulation that appear under the simulation tree. These icons are released under the Creative Commons Attribution 3.0 License, and they cannot be redistributed under the terms of the GPL.
+
+
+
+ And finally, I want to thank all the users who have contacted me - whether with bug reports, with suggestions, or just to let me know that they're using Logisim in their classes. I have to leave these suggesters anonymous, because I don't have their permission to mention them here, but: Thank you!
+
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/about/_index.html b/src/main/resources/doc/en/html/guide/about/_index.html
new file mode 100644
index 0000000000..a7fdbf01f8
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/about/_index.html
@@ -0,0 +1,115 @@
+
+
+
+
+
+
+
+
+
+ About the program
+
+
+
+
+
+
+ About the program
+
+
+ Logisim is open-source software. The source code is included in the src subdirectory of the distributed JAR file.
+
+
+ If you find Logisim useful, please let me know. Especially do this if you are an educational institution; the information will help me in gaining support for the work.
+
+
+
+
+
+ I welcome e-mails about Logisim, including bug reports, suggestions, and fixes. When you e-mail me, please remember that I have worked hard to produce Logisim without receiving any payment from you. If you want a right to complain about the software, then I would suggest shelling out the money for a competing program to Logisim. (I know of no open-source competitors that approach Logisim's feature set.) Nonetheless, I remain interested in continuing to improve Logisim, and your suggestions will be most welcome.
+
+
+ Copyright notice
+
+
+ Copyright (c) 2005, Carl Burch.
+
+
+ Logisim is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+
+
+ Logisim is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+
+ Acknowledgements
+
+
+ The source code to Logisim is primarily my own work; I must acknowledge my employers who fund my work as a professor, including this program: I started the program at Saint John's University (Collegeville, Minnesota, USA) in 2000-2004, and I have continued it at Hendrix College (Conway, Arkansas, USA) from 2004 to present. I am very grateful to these colleges for giving me the time and resources to work on this project. If only all colleges and universities had their act as together and cared as much about excellent teaching as these colleges do!
+
+
+ Some other people who have been particularly helpful:
+
+
+
Theldo Cruz Franqueira, Thanos Kakarountas, Ilia Lilov, Pablo Leal Ramos, and Uwe Zimmermann, who have contributed to translations packaged with Logisim. More information about the translations can be found on International Preferences page.
+
+
The Spring 2005 CS61C class at the University of California, Berkeley, which endured the beta versions of Logisim 2.0. These students put up with many bugs, and I am very appreciative for their patience and for their suggestions!
+
+
The Spring 2001 CSCI 150 classes at the College of Saint Benedict and Saint John's University, which used the most rudimentary versions of Logisim as it was being developed.
+
+
+
+ Several pieces of Logisim come from others' packages that Logisim uses; several of these pieces are distributed as part of Logisim.
+
+
+
+ Sun's Java API (obviously)
+
+
+ Sun's JavaHelp project
+
+
+ Provides the integrated help system from the Help menu.
+
+
+ MRJAdapter, from Steve Roy
+
+
+ Integration with the Macintosh OS X platform.
+
+
+ launch4j, from Grzegorz Kowalt
+
+
+ Allows distribution of Logisim as a Windows executable.
+
+
+ ColorPicker, from Jeremy Wood
+
+
+ Provides the color dialog box that pops up when configuring colors (as with the LED component).
+
+
+ JFontChooser, from Christos Bohoris
+
+
+ Provides the font selection dialog box that pops up when selecting font attributes (such as with the Label Font attribute of many components).
+
+
+ TableSorter, ascribed to Philip Milne, Brendon McLean, Dan van Enckevort, Parwinder Sekhon, and ouroborus@ouroborus.org
+
+
+ Provides the ability to sort the table in the Get Circuit Statistics dialog through clicking column headers.
+
+ Provides the icons for controlling simulation that appear under the simulation tree. These icons are released under the Creative Commons Attribution 3.0 License, and they cannot be redistributed under the terms of the GPL.
+
+
+
+ And finally, I want to thank all the users who have contacted me - whether with bug reports, with suggestions, or just to let me know that they're using Logisim in their classes. I have to leave these suggesters anonymous, because I don't have their permission to mention them here, but: Thank you!
+
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/about/gpl.html b/src/main/resources/doc/en/html/guide/about/gpl.html
new file mode 100644
index 0000000000..b687886cdb
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/about/gpl.html
@@ -0,0 +1,343 @@
+
+
+
+
+
+
+
+
+
+ GNU GENERAL PUBLIC LICENSE
+
+
+
+
+
+ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+
+ Preamble
+
+
+ The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+
+ The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+
+ When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+
+ To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+
+ For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+
+ Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+
+ For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+
+ Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+
+ Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+
+ The precise terms and conditions for copying, distribution and modification follow.
+
+
+ TERMS AND CONDITIONS
+
+
+ 0. Definitions.
+
+
+ “This License” refers to version 3 of the GNU General Public License.
+
+
+ “Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+
+ “The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+
+ To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+
+ A “covered work” means either the unmodified Program or a work based on the Program.
+
+
+ To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+
+ To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+
+ An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+
+ 1. Source Code.
+
+
+ The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+
+ A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+
+ The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+
+ The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+
+ The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+
+ The Corresponding Source for a work in source code form is that same work.
+
+
+ 2. Basic Permissions.
+
+
+ All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+
+ You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+
+ Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+
+ No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+
+ When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+
+ 4. Conveying Verbatim Copies.
+
+
+ You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+
+ You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+
+ 5. Conveying Modified Source Versions.
+
+
+ You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+
+
a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+
b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+
+
c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+
d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+
+
+ A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+
+ 6. Conveying Non-Source Forms.
+
+
+ You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+
+
a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+
b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+
c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+
d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+
e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+
+
+ A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+
+ A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+
+ “Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+
+ If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+
+ The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+
+ Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+
+ 7. Additional Terms.
+
+
+ “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+
+ When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+
+ Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+
+
a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+
b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+
c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+
d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+
e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+
f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+
+
+ All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+
+ If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+
+ Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+
+ 8. Termination.
+
+
+ You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+
+ However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+
+ Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+
+ Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+
+ 9. Acceptance Not Required for Having Copies.
+
+
+ You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+
+ 10. Automatic Licensing of Downstream Recipients.
+
+
+ Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+
+ An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+
+ You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+
+ 11. Patents.
+
+
+ A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+
+ A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+
+ Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+
+ In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+
+ If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+
+ If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+
+ A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+
+ Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+
+ 12. No Surrender of Others' Freedom.
+
+
+ If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+
+ 13. Use with the GNU Affero General Public License.
+
+
+ Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+
+ 14. Revised Versions of this License.
+
+
+ The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+
+ Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+
+ If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+
+ Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+
+ 15. Disclaimer of Warranty.
+
+
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+
+ 16. Limitation of Liability.
+
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+
+ 17. Interpretation of Sections 15 and 16.
+
+
+ If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/about/index.html b/src/main/resources/doc/en/html/guide/about/index.html
new file mode 100644
index 0000000000..d864b94cc7
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/about/index.html
@@ -0,0 +1,126 @@
+
+
+
+
+
+
+
+
+
+ About the program Logisim-evolution
+
+
+
+
+
+
+ About the program Logisim-evolution
+
+
+ Logisim Logisim is an educational tool for designing and simulating digital logic circuits. It has been originally created by Dr. Carl Burch and actively developed until 2011. After this date the author focused on other projects, and recently the development has been officially stopped (see his message here).
+
+ We have decided to release this new Logisim version under the name logisim-evolution, to highlight the large number of changes that occurred in these years, and we actively seek the contribution of the community.
+
+
+ This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (see below license)
+
+
+ What's new in logisim-evolution
+
+
+
Chronogram -- to see the evolution of signals in your circuit
+
+
Electronic board integration -- schematics can now be simulated on real hardware!
+
+
Board editor -- to add new electronic boards
+
+
VHDL component -- a new component type whose behavior is specified in VHDL le comportement est spécifié dans VHDL
+
+
TCL/TK console -- interfaces between the circuit and the user
+
+
DIP switches
+
+
RGB LEDs
+
+
Large number of bug-fixes
+
+
GUI improvements
+
+
Automatic updates
+
+
Code refactoring
+
+
...
+
+
+
+ Retro-compatibility
+
We cannot assure retro-compatibility of logisim-evolution with files created with the original Logisim. We have incorporated a parser that alters the name of the components to satisfy VHDL requirements for variable names, but components evolved in shape since then (think, for instance, to RAM and counters). You might need to rework a bit your circuits when opening them with logisim-evolution -- but the changes will be stored in the new format, therefore you have to do your work only once.
+
+ Wish-list
+
+
+ Logisim-evolution is a continuously-growing software, and we have several ideas we would like to implement. In particular, we would like to have:
+
unit tests for the code
+
+
extensive documentation
+
+
test circuits
+
+
... If you are willing to contribute with any of these, please feel free to contact us!
+
+
+
+ How to get support for logisim-evolution
+
+
+ Unfortunately, we do not have enough resources to provide direct support for logisim-evolution. We will, however, try to deal with the raised issues in a best-effort way.
+
+
+ If you find a bug or have an idea for an interesting feature, please do not hesitate to open a ticket!
+
+ For each output variable, the Combinational Analysis window maintains two structures - the relevant column of the truth table, and a Boolean expression - specifying how each output relates to its input. You can edit either the truth table or the expression; the other will automatically change as necessary to keep them consistent.
+
+
+ As we will see on the next page, the Boolean expressions are particularly useful because the Combinational Analysis window will use these when told to build a circuit corresponding to the current state.
+
+
+ You can view and edit the expressions using the window's last two tabs, the Expression tab and the Minimized tab.
+
+
+ The Expression tab
+
+
+
+
+
+ The Expression tab allows you to view and edit the current expression associated with each output variable. It presents a "Notation: " selector and a list of the mathematical expressions of the circuit.
+
+
+ The Notation : selector: changes the notation mode of the output expressions. It allows you to choose from five types of notation:
+
+
Mathematical :
The bar above represents the negation, Le - the AND function and the + the OR function.
+
Logical :
The ¬ represents the negation, the ˄ the AND function and the ˅ the OR function.
+
Alternative Logical :
The ~ represents the negation, the ˄ the AND function and the ˅ the OR function.
+
Programming with Boolean's :
The ! represents the negation, the && the AND function and the || the OR function.
+
Programming with bits :
The ~ represents the negation, the & represents the AND function and the | represents the OR function.
+
+
+
+ Just below the selector, the expressions are displayed in a list. You can edit the expression in the text panel by double-clicking on the line of the expression.
+
+
+ Note that your truth table will be irretrievably altered if you edit the expressions and vice versa.
+
+
+ The text pane below this displays the same information in ASCII form. Here, a NOT is represented with a tilde ('~').
+
+
+
+ You can edit the expression in the text pane and click the Enter button to make it take effect; doing this will also update the truth table to make it correspond. The Clear button clears the text pane, and the Revert button changes the pane back to representing the current expression.
+
+
+ Note that your edited expression will be lost if you edit the truth table.
+
+
+ In addition to multiplication and addition standing for AND and OR, an expression you type may contain any of C/Java logical operators, as well as simply the words themselves.
+
+
+
+
+
+
+ highest precedence
+
+
+ ~!'
+
+
+ NOT
+
+
+
+
+
+ (none) &&&
+
+
+ AND
+
+
+
+
+
+ ^
+
+
+ XOR
+
+
+
+
+ lowest precedence
+
+
+ +|||
+
+
+ OR
+
+
+
+
+
+
+ The following examples are all valid representations of the same expression. You could also mix the operators.
+
+
+
+
+
+ a' (b + c)
+
+
+
+
+ !a && (b || c)
+
+
+
+
+ NOT a AND (b OR c)
+
+
+
+
+
+ In general, parentheses within a sequence of ANDs (or ORs or XORs) do not matter. (In particular, when Logisim creates a corresponding circuit, it will ignore such parentheses.)
+
+
+ The Minimized tab
+
+
+
+
+
+ The last tab displays the minimum expression of one of the columns of the truth table. On this panel there are four selectors, the karnaught table and the minimal expression.
+
+
+ With the top selector Output:, you can select the minimized output of a column of the table you want to display.
+
+
+ The following selector Format:: allows you to indicate whether you want to produce a sum of products or a sum of sums.
+
+
+ the selector Style: modulates the presentation of variables on the table edges. Either with binary values or with lines on the true values.
+
+ A Karnaugh map corresponding to the variable will appear below the selector. You can click the Karnaugh map to change the corresponding truth table values. The Karnaugh map will also display the currently selected terms for the minimized expression as solid semitransparent rounded rectangles.
+
+
+ Below this is the minimized expression itself, formatted as in the Expression tab's display. Logisim uses the Quine-McCluskey algorithm to compute the minimized expression. This is equivalent to a Karnaugh map, but it applies to any number of input variables.
+
+
+ The Set As Expression button allows you to select the minimized expression as the expression corresponding to the variable. This will generally not be necessary, as edits to the truth table result in using the minimized expression for the changed column; but if you enter an expression through the Expression tab, this can be a convenient way to switch to the corresponding minimized expression.
+
+ The Build Circuit button will construct a circuit whose gates correspond to the currently chosen expressions for each output. The circuit's inputs and outputs will be displayed in top-down order corresponding to how they appear under the Inputs and Outputs tabs. Generally speaking, the constructed circuit will be attractive; and, indeed, one application of Logisim's Combinational Analysis module is to beautify poorly drawn circuits. Still, as with any automatic formatting, it will not express the structural details that a human-drawn circuit would.
+
+
+
+
+
+ When you click the Build Circuit button, a dialog box will appear prompting you to choose which project where you want the circuit and the name you wish to give it.
+
+
+
+
+
+ If you type the name of an existing circuit, then that circuit will be replaced (after Logisim prompts you to confirm that you really want to do this).
+
+
+ The Build Circuit dialog includes two options.
+
+
+
The Use Two-Input Gates Only option specifies that you want all gates constructed to have two inputs. (NOT gates, of course, constitute an exception to this rule.)
+
+
TheUse NAND Gates Only option specifies that you would like it to translate the circuit into one using only NAND gates. You can select both options if you want to use only two-input NAND gates.
+
+
+
+ Logisim cannot construct a NAND-only circuit for an expression containing any XOR operators. This option will therefore be disabled if any outputs' expressions contain XORs.
+
+ The bulk of the Combinational Analysis module is accessed through a single window of that name allowing you to view truth tables and Boolean expressions. This window can be opened in two ways.
+
+
+ Via the Window menu
+
+
+ Select | Window |→| Combinational Analysis |, and the current Combinational Analysis window will appear. If you haven't viewed the window before,the opened window will represent no circuit at all.
+
+
+ Only one Combinational Analysis window exists within Logisim, no matter how many projects are open. There is no way to have two different analysis windows open at once.
+
+
+ Via the Project menu
+
+
+ From a window for editing circuits, you can also request that Logisim analyze the current circuit by selecting the Analyze Circuit option from the menu | Project |→| Analyze Circuit |. Before Logisim opens the window, it will compute Boolean expressions and a truth table corresponding to the circuit and place them there for you to view.
+
+
+ For the analysis to be successful, each input must be attached to an input pin, and each output must be attached to an output pin. Logisim will only analyze circuits with at most eight of each type, and all should be single-bit pins. Otherwise, you will see an error message and the window will not open.
+
+
+ In constructing Boolean expressions corresponding to a circuit, Logisim will first attempt to construct a Boolean expressions corresponding exactly to the gates in the circuit. But if the circuit uses some non-gate components (such as a multiplexer), or if the circuit is more than 100 levels deep (unlikely), then it will pop up a dialog box telling you that deriving Boolean expressions was impossible, and Logisim will instead derive the expressions based on the truth table, which will be derived by quietly trying each combination of inputs and reading the resulting outputs.
+
+
+ After analyzing a circuit, there is no continuing relationship between the circuit and the Combinational Analysis window. That is, changes to the circuit will not be reflected in the window, nor will changes to the Boolean expressions and/or truth table in the window be reflected in the circuit. Of course, you are always free to analyze a circuit again; and, as we will see later, you can replace the circuit with a circuit corresponding to what appears in the Combinational Analysis window.
+
+
+ Limitations
+
+
+ Logisim will not attempt to detect sequential circuits: If you tell it to analyze a sequential circuit, it will still create a truth table and corresponding Boolean expressions, although these will not accurately summarize the circuit behavior. (In fact, detecting sequential circuits is provably impossible, as it would amount to solving the Halting Problem. Of course, you might hope that Logisim would make at least some attempt - perhaps look for flip-flops or cycles in the wires - but it does not.) As a result, the Combinational Analysis system should not be used indiscriminately: Only use it when you are indeed sure that the circuit you are analyzing is indeed combinational!
+
+
+ Logisim will make a change to the original circuit that is perhaps unexpected: The Combinational Analysis system requires that each input and output have a unique name that conforming to the rules for Java identifiers. (Roughly, each character must either a letter or a digit, and the first character must be a letter. No spaces allowed!) It attempts to use the pins' existing labels, and to use a list of defaults if no label exists. If an existing label doesn't follow the Java-identifier rule, then Logisim will attempt to extract a valid name from the label if at all possible.
+
+
+ Incidentally, the ordering of the inputs in the truth table will match their top-down ordering in the original circuit, with ties being broken in left-right order. (The same applies to the ordering of outputs.)
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/analyze/ana-table.html b/src/main/resources/doc/en/html/guide/analyze/ana-table.html
new file mode 100644
index 0000000000..88aa28f1e7
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/analyze/ana-table.html
@@ -0,0 +1,76 @@
+
+
+
+
+
+
+
+
+
+ Editing the truth table
+
+
+
+
+
+
+ Editing the truth table
+
+
+ On opening the Combinational Analysis window, you will see that it consists of four tabs.
+
+
+ This page describes the first two tabs, Inputs & Outputs, and Table. The next page of the guide describes the last two tabs, Expression and Minimized.
+
+
+ The Inputs & Outputs tabs
+
+
+
+
+
+ The Inputs & Outputs tab allows you to display and edit lists of inputs and/or outputs and to specify the width of their data.
+
+
To add items to the list, simply select the line with Up Arrow or Down Arrow or click on "Click to..." and enter the desired name. You can see above the line "c_out" inserted in the list of outputs. Then you can define the data width of this line (on the right) with the mouse. The Enter or Tab key will end the input.
+
+
+ If you want to rename one of the existing lines, a double click on the text will allow you to modify it.
+
+
+ To delete a line, select it as before with the mouse or the Up Arrow or Down Arrow and then use the Delete key.
+
+
To rearrange the order of the rows, select it as above, then use the Ctrl+Up Arrow or Ctrl+Down Arrow combination to move it up or down in the list.
+
+
+ All actions affect the truth table immediately.
+
+
+ The Table tab
+
+
+ In the Table tab you will find a series of buttons and the current truth table., diagrammed in the conventional order, with inputs constituting the columns on the left and outputs constituting the columns on the right.
+
+
+
+
+
+ You can edit the current values appearing in the output columns by clicking on the value of interest. You can change the current values in the output columns by clicking on the value you are interested in and using the keyboard keys 0,1 and - (representing an undefined value) or in the top the buttons - , 1 , 0 . After entering the value, the cursor moves down one line in the column.
+ The key combinations Ctrl+Up/Down Arrow or Ctrl+Left/Right Arrow are used to move the selection.
+
+
In the same way, you can modify the data in the input columns by inserting indeterminate values (-) or to delete them and replace them with 0 or 1.
+
+
+ In this context the buttonCollapse duplicate rows simplifies the representation of the table and Show all rows in its entirety.
+
+
+ You can copy and paste values using the clipboard. The clipboard can be transferred to any application supporting tab-delimited text (such as a spreadsheet).
+
+
+ If the truth table is based on an existing circuit, you may see some red squares in the output columns with "E" in them. These correspond to errors that occurred while calculating the value for that row - either the circuit seemed to be oscillating, or the output value was an error value (which would be pictured as a red wire in the Logisim circuit).
+
+ All circuits fall into one of two well-known categories: In a combinational circuit, all circuit outputs are a strict combination of the current circuit inputs, whereas in a sequential circuit, some outputs may depend on past inputs (the sequence of inputs over time).
+
+
+ The category of combinational circuits is the simpler of the two. Practitioners use three major techniques for summarizing the behavior of such circuits.
+
+
+
+
+
+
logic circuits
+
+
Boolean expressions, which allow an algebraic representation of how the circuit works
+
+
truth tables, which list all possible input combinations and the corresponding outputs
+
+
+
+ The Combinational Analysis module of Logisim allows you to convert between these three representations in all directions. It is a particularly handy way of creating and understanding circuits with a handful of one-bit inputs and outputs.
+
+
+ Note: the combinatorial analysis is deactivated in Logisim-evolution. It is possible to reactivate with a command-line option.
+
+ This option allows you to place components with self-numbered labels for example Led_1, Led_2... . To use it, proceed as follows :
+
+
+ Select a tool in the navigation panel, for example a Pin, and move it to the work surface and before clicking to drop it press the L key.
+
+ Enter a label name ending with a number, e.g. "In_1".
+
+
+
+
+
+ From now on when you drop components of this type they will be automatically labeled with an increment. When the option is activated, the shadow of the components before their placement is colored pink.
+ It is possible to activate this option for different components simultaneously.
+
+
+
+
+
+ To deactivate, proceed in the same way as for activation, but use the A key. If you have activated self-labelling on components of a different type. You must deactivate it individually for each component type.
+
+
+ Keys and associated functions
+
+ L : Activates the function and set/Modify Label
+ T : Toggle label visibility
+ H : Set label visibility to false (hide)
+ V : Set label visibility to true (show)
+ A : Ends the self-numbered label function
+
+ We are now in a position to summarize the full rainbow of colors that Logisim wires can take on. The following little circuit illustrates all of them at once.
+
+
+
+
+
+
+
+ Gray: The wire's bit width is unknown. This occurs because the wire is not attached to any components' inputs and outputs. (All inputs and outputs have a defined bit width.)
+
+
+
+
+ Blue: The wire carries a one-bit value, but nothing is driving a specific value onto the wire. We call this a floating bit; some people call it a high-impedance value. In this example, the component placing a value onto the wire is a three-state pin, so it can emit this floating value.
+
+
+
+
+ Dark green: The wire is carrying a one-bit 0 value.
+
+
+
+
+ Bright green: The wire is carrying a one-bit 1 value.
+
+
+
+
+ Black: The wire is carrying a multi-bit value. Some or all of the bits may not be specified.
+
+
+
+
+ Red: The wire is carrying an error value. This often arises because a gate cannot determine the proper output, perhaps because it has no inputs. It could also arise because two components are trying to send different values onto the wire; this is what happens in the above example, where one input pin places 0 onto the wire while another places 1 onto the same wire, causing a conflict. Multi-bit wires will turn red when any of the bits carried are error values.
+
+
+
+
+ Orange: The components attached to the wire do not agree in bit width. An orange wire is effectively "broken": It does not carry values between components. Here, we've attached a two-bit component to a one-bit component, so they are incompatible.
+
+
+
+
+ Green-Fuchsia: This color scheme indicates that the wire was selected with the tool push (). This allows us to know the way and also the indication of the state of the line will be displayed in a small bubble and it also allows to follow a connection in a complex scheme.
+
+ In simple Logisim circuits, most wires carry only one bit; but Logisim also allows you to create wires that bundle together multiple bits. The number of bits traveling along a wire is that wire's bit width.
+
+
+ Every input and output on every component in the circuit has a bit width associated with it. Often the bit width is 1, and there is no way of changing that, but many of Logisim's built-in components include attributes allowing you to customize the bit widths of their inputs and outputs.
+
+
+ The below screen shot illustrates a simple circuit for finding the bitwise AND of two three-bit inputs. Notice how the three-bit output is the bitwise AND of the two inputs. All components have been customized to deal with three-bit data via its Data Bits attribute; the screen shot shows the AND gate attributes, including the Data Bits attribute of 3.
+
+
+
+
+
+ All components in Logisim define a bit width for each of input and output. In contrast, a wire's bit width is undefined: Instead, the wire's width adapts to the components to which it is attached. If a wire connects two components demanding different bit widths, Logisim will complain of "Incompatible widths" and indicate the offending locations in orange. In the below, the output pin's Data Bits attribute has been changed to 1, and so Logisim complains that the wire cannot connect a three-bit value to a one-bit value.
+
+
+
+
+
+ Wires that connect incompatible locations (drawn in orange) do not carry values.
+
+
+ For single-bit wires, you can see at a glance what value the wire carries because Logisim colors the wire light or dark green depending the value. It does not display values for multi-bit wires: They are simply black. You can, though, probe a wire by clicking it using the "poke" tool ().
+
+
+
+
+
+ This probing feature is helpful for debugging circuits using wire bundles.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/feature/fet-matrix.html b/src/main/resources/doc/en/html/guide/feature/fet-matrix.html
new file mode 100644
index 0000000000..cd240e2908
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/feature/fet-matrix.html
@@ -0,0 +1,38 @@
+
+
+
+
+
+
+
+
+
+ Placing components in a matrix
+
+
+
+
+
+
+ Placing components in a matrix
+
+
+ In Logisim-evolution it is possible to place matrix components on your schematic. To do so, proceed as follows:
+ Select the desired tool in the navigation panel for example the LED, and move it on the work surface and before clicking to drop it press the X key . The shadow of the component will turn into a small 2 by 2 matrix of the component.
+
+
+
+
+
+ Click on the top left of the position where you want to place the future matrix. And fill in the form data. For example: 4x5 elements with a space of 4.
+
+
+
+ If self-labeling is enabled, components will be labeled as _X_Y, Example: Led_X1_Y0
+
+
+ When you work with multi-bit values, you will often want to route different bits in different directions. The Wiring library's splitter tool () allows you to accomplish this.
+
+
+ For example, suppose we want a circuit that computes the bitwise AND of the two nibbles of its eight-bit input (the upper four bits and the lower four bits). We will have an eight-bit value coming from the input pin, and we want to split that into two four-bit values. In the below circuit, we have used a splitter to accomplish this: The 8-bit input comes into the splitter, which divides the 8 bits into two 4-bit values, which are then fed into the AND gate and from there to the output.
+
+
+
+
+
+ In this example, the splitter splits an incoming value into multiple outgoing values. But splitters can also work the other way: It can combine multiple values into a single value. In fact, they are non-directional: They can send values one way at one time and another way later, and they can even do both at the same time, as in the below example where a value travels eastward through the two splitters, then is routed back westward through them again, and then back eastward where it finally reaches its output.
+
+
+
+
+
+ The key to understanding splitters is their attributes. In the following, the term Split End refers to one of the multiple wires on one side, while the term data bus refers to the single wire on the other side.
+
+
+
The Facing attribute tells where the split ends should be relative to the Fan Out.
+
+
+
+
+
+ Data bus
+
+
+
+
+
+
+ Split End
+
+
+
+
+
+
+
The Fan Out attribute specifies how many split ends there are.
+
+
The Appearence defines how the split end is drawn relative to its data bus.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Right
+
+
+ Left
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Center
+
+
+ Legacy
+
+
+
+
+
+
+
The Bit Width In attribute specifies the bit width of the combined end.
+
+
+ The Bit x attributes define which separate split end corresponds to which bit x of the data bus. It is modifiable and allows you to organize the order of split end by hand. If several bits correspond to the same split end (first example above), then the relative order will be the same as in the bus. Logisim distributors cannot have a bus bit linked to more than one split end.
+
+
+
+ Note that any change to the Fan Out or Bit Width In attributes will reset all Bit x attributes so that they will distribute the bits of the combined value as evenly as possible among the split ends.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/gui/gui-attrcomp.html b/src/main/resources/doc/en/html/guide/gui/gui-attrcomp.html
new file mode 100644
index 0000000000..44543ebf47
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/gui/gui-attrcomp.html
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+ Attributes of tools and components
+
+
+
+
+
+
+ Attributes of tools and components
+
+
+ Every tool for adding components to a circuit also has a set of attributes, which are imparted to the components created by the tool, although the components' attributes may be changed later without affecting the tool's attributes. When you select a tool, Logisim will change the attribute table to display that tool's attributes.
+
+
+ For example, suppose we want to create smaller AND gates. Right now, each time we select the AND tool, it creates a large AND gate. But if we edit the Gate Size attribute just after selecting the tool (before placing its AND gate into the circuit), we'll be changing the attributes for the tool, so that future AND gates added using the tool would be narrow instead.
+
+
+
+
+
+ Now, we can delete the two existing AND gates and add two new AND gates in their place. This time, they will be narrow. (If you chose to reduce the number of inputs to 3, the AND gate would not have vertical extension on the left side. But you'd also have to rewire the circuit so that the wires hit the AND gate's left side.)
+
+
+
+
+
+ With some tools, the tool's icon reflects some of the attributes' values. One example of this is the Pin tool, whose icon faces the same way as its Facing attribute says.
+
+
+ The tools in the toolbar each have a separate attribute set from the corresponding tools in the explorer pane. Thus, even though we changed the toolbar's AND tool to create narrow AND gates, the AND tool in the Gates library will still create wide AND gates unless you change its attributes too.
+
+
+ In fact, the input pin and output pin tools in the default toolbar are both instances of the Wiring library's Pin tool, but the attribute sets are different. The icon for the Pin tool is drawn as a circle or a square depending on the value of its Output? attribute.
+
+
+
+
+
+ Logisim provides a handy shortcut for changing the Facing attribute that controls the direction in which many components face: Typing an arrow key while that tool is selected automatically changes the direction of the component.
+
+ Many components have attributes, which are properties for configuring how the component behaves or appears. The attribute table is for viewing and displaying a component's attribute values.
+
+
+ To select which component's attributes you wish to view, click the component using the Edit tool (). (You can also right-click or control-click the component and choose Show Attributes from the popup menu. Also, manipulating a component via the Poke tool () or the Text tool () will display that component's attributes.)
+
+
+ The below screen shot demonstrates what things look like after selecting the upper input of our XOR circuit and scrolling down to view the Label Font attribute.
+
+
+
+
+
+ To modify an attribute value, click on the value. The interface for modifying the attribute will depend on which attribute you are changing; in the case of the Label Font attribute, a dialog box will appear for selecting the new font; but some attributes (like Label) will allow you to edit the value as a text field, while others (like Label Location) will display a drop-down menu from which to select the value.
+
+
+ Each component type has a different set of attributes; to learn what they mean, go to the relevant documentation in the Library Reference.
+
+
+ If you've selected multiple components using the Edit tool (), then the attribute table will display attributes that are shared among all the selected components (excluding any wires). If the selected components don't all have the same value for the attribute, then the displayed value will be blank. You can change the value for all selected components' attribute at once by using the attribute table.
+
+ The canvas is really the most visible part of Liogisim-evolution is where you draw your circuits and their symbol to finally simulate the operation.
+
+
+
+
+
+ It is composed of only a few elements:
+
+
+ Horizontal and vertical scroll bars : They work as in most programs, just drag the sliders to move the view to other parts of the drawing. They can also be manipulated from the keyboard or mouse with the following combinations:
+
+
+
Mouse wheel or keys up/down arrow : vertical scrolling
+
+
+ Alt-Mouse wheel or keys right/left arrow: horizontal scrolling
+
+
Key PgUp : go to the top of the page
+
+
Key PgDn : go to bottom of page
+
+
+
+ Range indicators when the schematic is larger than the display area of the indicators are displayed. The guides displayed in the corners and / or on the sides indicate the directions where the drawing extends. Below is an example of the indicators on the top of the page.
+
+
+
+
The centering button It places the center of the diagram in the center of the work surface.
+
+
+
+ The zoom: At the bottom left is the control of the zoom factor. You can change it by dragging the cursor or using one of the two buttons to the left and right of the rate or with Ctrl - mouse wheel in the work area.
+
+
+
+
+
+ The button 100% :fits the zoom to display the diagram at its actual size.
+ The button Auto : fits the zoom so that the whole diagram is visible.
+ The grid button : On the right of the zoom, Toggle mode alternately "grid displayed" in the mode "invisible grid".
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/gui/gui-explore.html b/src/main/resources/doc/en/html/guide/gui/gui-explore.html
new file mode 100644
index 0000000000..c72022af4a
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/gui/gui-explore.html
@@ -0,0 +1,118 @@
+
+
+
+
+
+
+
+
+
+ The explorer pane
+
+
+
+
+
+
+ The explorer pane
+
+
+
+
+
+
+
+
+ The navigation panel has two functions. It can present the circuits being simulated in the view simulation or as here the circuits in the top of the list and the lower libraries represented by folder icons. These libraries include tools you can use in your projects.
+
+
+
+
+
+ To access the components of a library just open the library with a double-click the corresponding folder or a click on the tiny key then select the tool with a right-click on the tool. Then move the mouse cursor over the canvas and a ghost drawing of the tool will follow the mouse cursor until you make the last click on the surface to drop it to the chosen location.
+
+
+ Below, I have opened the Gates library and selected the NAND tool from it. You can see that Logisim now stands ready to add NAND gates into the circuit.
+
+
+
+
+
+ If you look through the choices in the Gates library, you'll notice that there was no need for us to develop a XOR circuit earlier: It's built into Logisim.
+
+
+ When you create a project, it automatically includes several libraries:
+
+
+
+ Wiring : Components that interact directly with wires.
+
+
+ Gates : Components that perform simple logic functions.
+
+
+ Plexers : More complex combinational components, like multiplexers and decoders.
+
+
+ Arithmetic : Components that perform arithmetic.
+
+
+ Memory : Components that remember data, like flip-flops, registers, and RAM.
+
+
+ I/O : Components that exist for the purpose of interacting with the user.
+
+
+
+ TCL : I did not document for the moment
+
+
+ HDL-IP : I did not document for the moment
+
+
+ BFH mega function : I did not document for the moment
+
+
+
+ Libraries
+
+
+ Logisim allows you to add more libraries, too, using the menu | Project | → | Load Library | or by left-clicking on the root folder of the project explorer. You can see that Logisim has three categories of libraries.
+
+
+
+ Built-in libraries are libraries that are distributed with Logisim. These are documented in the Library Reference.
+
+
+ Logisim libraries are projects built within Logisim and saved to the disk as a Logisim project. You can develop a set of circuits in a single project (as described in the Subcircuits section of this guide) and then use that set of circuits as a library for other projects.
+
+
+ JAR libraries are libraries that are developed in Java but not distributed with Logisim. You can download JAR libraries that others have written, or you can write your own as described in the JAR Libraries section of this guide. Developing a JAR library is much more difficult than developing a Logisim library, but the components can be much fancier, including things like attributes and interaction with the user. The built-in libraries (other than Base") were written using the same API as JAR libraries can use, so they aptly demonstrate the range of functionality that the JAR libraries can support.
+
+ Some JAR libraries are distributed without any information about which Java class to start with. When loading such a JAR, Logisim will prompt you to type a class name. This class name should be provided by whoever distributed the JAR file to you.
+
+
+
+
+ To remove a library, choose menu | Project |→| Unload Library ... |. Logisim will prevent you from unloading libraries that contain components used in a circuit, that appear in the toolbar, or that are mapped to a mouse button.
+
+
+
+
+
+ It is also possible to do this by pressing a click-left on the library to disable.
+
+
+ Incidentally, a library technically contains tools, not components. Thus, in the Base library you'll find the Poke Tool (), the Edit Tool (), and other tools that don't correspond directly to individual components. Most libraries, though, contain only tools for adding individual components.
+
+
+ This section quickly explains the seven menus that accompany each major logisim window.
+
+
+ The File menu : This menu allows you to open close to save projects. It gives access to preferences and allows you to leave the program.
+
+
+ The Edit menu : Mainly used to edit, copy, delete, duplicate, move drawing elements.
+
+
+ The Project menu : Lets you manage libraries, change the order in the navigation pane, and change the appearance of this pane. It gives access to project preferences.
+
+
+ The Simulation menu : Control the simulation, start, stop, go into step mode, start the clocks.
+
+
+ The Window menu :RMinimize, Expand, close windows. Go to the Combinatorial Analysis window (if enabled) and application preferences.
+
+
+ The Window menu :Minimize, Expand, close windows. Go to the Combination Analysis window (if enabled) and the application preferences.
+
+
+ The Help menu :Go to the tutorial, the reference guide or the reference of the libraries.
+
+ Logisim-evolution has several toolbars. The main toolbar is configurable and provides quick access to the most used tools. These are also always available in the navigation pane.
+
+
+
+ The bar in "Drawing" mode
+
+
+
+ The bar in "Appearance" mode
+
+
+ And finally two more bars appear depending on the status of the navigation panel. They are presented below.
+
+
+
+
+
+ The main toolbar
+
+
+ This toolbar with two presentations (see above) according to the editing mode chooses "Drawing" or "Appearance"
+
+
+ The bar in the mode "drawing"
+
+
+ In the "Drawing" mode it is customizable using the | Projet |→| Options |menu tab | Barre d'outils | The configuration is presented by the page on The Toolbar tab. Below we briefly present the default tools in the bar. There are many other components to build circuits. You will find a lot more information about all the tools in the Library Reference
+
+
+
+
+
+
+
+
+ Poke tool :Ctrl-1 This tool allows you to interact with the simulation components. For example if you push on a circuit connection it will switch from one state to another or if push on a cable you can know the value of the signals transported. More information on the link poke from the library base
+
+
+
+
+
+
+
+ Selection tool :Ctrl-2 This tool is particularly useful when designing circuits, it allows to ask, move or select the elements. It is also used to wire the circuit. More information on the link select from the library base
+
+
+
+
+
+
+
+ Wiring tool :Ctrl-3 This tool allows you to place cables on the diagram.
+
+
+
+
+
+
+
+ Text Tool :Ctrl-4 This tool makes it possible to place text on the drawings and to modify the labels of the components. More information on the link Text from the library base
+
+
+
+
+
+
+
+ Pin Tool broche :Ctrl-5 / 6 This tool makes it possible to place connection pins on the diagram. The connections are of two types: input or output. They are presented in this page Pin from the library Wiring
+
+
+
+
+
+
+
+ Tools Not,And,Or... :Ctrl-7 / 8 / 9 / 0 These tools make it possible to place the basic logic gates on the drawing. Logic gates are presented in the Gates library
+
+
+
+
+
+ The bar in mode "Appearance" mode
+
+
+ In this mode or we can edit the symbol of a sub-circuit. the bar offers drawing tools. You will find a little more information on the use in Editing subcircuit appearance
+
+ Curve tool: Create a Bezier curve. The first click and drag specifies the beginning of the line, the second click and drag ends the line and sets the curvature. A click on the line shows you the three control points. Schift and click on central control point impose a symmetrical curve. Alt click on center point draws the curve through the control point (under the mouse).
+
+
+
+
+
+
+
+ Polylines tool Creates a sequence of connected lines, each click starts a new line. A double-click ends the sequence.
+
+
+
+
+
+
+
+ Rectangle tool Create a rectangle or a square ( Shift ) by dragging from an angle to the opposite corner.
+
+
+
+
+
+
+
+ Round Rectangle tool : Creates a rectangle or square with a rounded edge (Maj) dragging from an angle to the opposite corner.
+
+
+
+
+
+
+
+ Oval tool Creates an oval or circle ( Shift ) by dragging from an angle to the opposite corner.
+
+
+
+
+
+
+
+ Polygon tool Create a polygon, each click starts a new face. A double-click ends the sequence.
+
+
+
+
+
+
+ The navigation panel tabs toolbar
+
+
+ This toolbar area displays two bars depending on the tabs of the program. The first has four buttons and is displayed when the program is in "drawing" mode. These are shortcuts to some of the menu submenu | Project |.
+
+
+
+
+
+
+
+
+ Add a circuit : Adds a new crcuit to our projects.
+
+
+
+
+
+
+
+ VHDL:Add a new VHDL circuit to our projects.
+
+
+
+
+
+
+
+ Bring up the circuit in the project hierarchy.
+
+
+
+
+
+
+
+ Bring down the circuit in the project hierarchy.
+
+
+
+
+
+
+
+ Edition mode: Toggles from schema mode to appearance edit mode alternately.
+
+
+
+
+
+
+
+ Deletes a circuit in the project hierarchy.
+
+
+
+
+
+ The second is displayed when the program is in the simulation tree view. These are shortcuts to some of the menu submenus | Simulate |
+
+
+
+
+
+
+
+
+
+ Enabled/disabled : Ctrl-E Enabled/disabled the simulation.
+
+
+
+
+
+
+
+ Step simulation : Ctrl-I Take a step forward in the simulation.
+
In Logisim, you can use VHDL to create new components called
+ VHDL entities. Those components can then be used in the
+ simulator, providing you have Questa Advanced Simulator installed
+ and configured adequately.
+
+
+
See below for more information about the VHDL entities and how to use
+ them in a simulation context.
+
Questa Advanced Simulator can be optionally used to validate VHDL
+ entities, and is required for any simulation using a VHDL entity.
+
+
+
By default, the VHDL validation with Questa Advanced Simulator is
+ disabled. In order to active it, you need to go in the Window
+ menu, Perferences and then in the Third Party Softwares
+ tab. You can then enable the validation by clicking on the Use
+ Questa Advanced Simulator to validate VHDL entities checkbox.
+
+
+
+
+
Right below that option, you can also set the path to your Questa
+ Advanced Simulator installation directory. In order to do so, simply
+ click the Browse... button and select the corresponding
+ directory. If you activate the validation but do not set the path,
+ you will be prompted to select it the next time a VHDL validation
+ occurs.
+
+
+
Note: You will also be prompted for the path if you
+ try to run a simulation of a circuit that includes a VHDL entity.
+
Logisim cannot directly perform VHDL content simulation. Instead,
+ QuestaSim is used as a background task.
+
+
+
Enable simulator
+
+
You can enable the simulator through the Simulate > VHDL
+ Simulation Enabled menu. When you do this, the simulator console
+ log appears on the bottom of the drawing pane. At the bottom bar of
+ the simulator log, you have the simulator status indicator. The
+ states are :
+
+
+
+
+
+ Disabled (console disappears)
+
+
+ Enabled (but inactive)
+
+
+ Starting
+
+
+ Active
+
+
+
+
+
The simulator starts automatically when it's enabled and the circuit
+ contains VHDL components. It is not possible to start the simulator
+ when there aren't any VHDL components in the circuit.
+
+
+
Restart
+
+
The VHDL simulation is restarted when you reset the Logisim
+ simulation. This concerns only the simulation state, it does not
+ reload the simulation (and the source files).
+
+
+
If you have changed the content of some VHDL component you have to
+ restart the VHDL simulator. This is never done automatically. You can
+ restart the simulator through the Simulate menu.
+
+
+
Time
+
+
The QuestaSim simulation step time has to be considered
+ unpredictable, as it depends on the number of VHDL components in the
+ circuit. The absolute minimum step is 100ns. Therefore, usage of
+ time-based simulation events must be avoided (like wait for
+ 10ns). You must only have signal-based events.
+
+
+
+
Multiple instances
+
+
Actually, you can only have a single instance of VHDL simulator.
+ That means that you have to disable it on the first project if you
+ want to have it enabled on a second one. If you try to enable it on
+ two projects it will fail and show you an error message.
+
You can add a test bench to your circuit to test it, but you have to
+ consider the following restrictions due to the simulation
+ architecture.
+
+
+
+
+
Simulation must be driven by Logisim
+
+
You cannot add event generating elements to your test bench, for
+ example, you cannot add a clock generator process. Your test bench
+ must take an external clock from Logisim as input.
+
+
+
Don't use time based conditions
+
+
The time representation does not exist in Logisim, no you cannot have
+ event based on time, for example wait for 5 ns. If you want to
+ make asynchronous verification, you must add a sysclk who has
+ at least twice the frequency of the mainclk. This way, you will be
+ able to check the signals not only on the main clock rising edges but
+ at any time you need.
+
A VHDL entity is a component that can be described using VHDL. It
+ comes with an editor which can be used to edit the entity and to
+ validate it, providing you have Questa Advanced Simulator installed
+ on your system.
+
+
+
Creating a VHDL entity
+
+
To create a new VHDL entity, simply open the HDL IP library in
+ the explorer panel and click on the VHDL Entity
+ component. If the library is not available, you will need to load it:
+ go to the Project menu, Load Library then Build-in
+ Library and select HDL IP from the menu.
+
+
+
+
+
Editing a VHDL entity
+
+
+
+
A new VHDL entity comes with a default template which contains two
+ inputs and two outputs. The entity can be edited by clicking on the
+ content attribute, as shown below.
+
+
+
+
+
The integrated HDL editor can then be used to modify the entity using
+ VHDL directly. You can also import the content of a VHDL file by
+ clicking the Import... button, or export your own code by
+ clicking the Export... button.
+
+
+
+
+
As you edit your component, the Validate Content button will
+ light up. It can be used to check if your code is valid, as long as
+ you have Questa Advanced Simulator installed and configured (see
+ Configuring Questa Advanced Simulator for
+ more information). If it is the case, clicking the Validate
+ button will compile the VHDL code, check for errors and display a
+ window with more information if any is found. If your code is valid,
+ the button will simply be deactivated until you make further
+ modifications.
+
+
+
Note: If you don't have Questa Advanced Simulator,
+ or if it is disabled, Logisim will nonetheless make a few checks,
+ mostly on the ports description.
+
+
+
When you are done editing your entity, you can click the Close
+ Window button. The code will be validated by Questa Advanced
+ Simulator if it is installed and enabled, and Logisim will
+ automatically regenerate your entity's symbol, adding, removing or
+ updating any port you might have added, removed or changed in your
+ code. If an error occurs during the validation process, a window
+ containing more information will be displayed, and you will be given
+ three choices:
+
+
+
+
Close anyway and discard all modifications.
+ This is achieved by clicking Yes. Please note any changes
+ done to your entity will be permanently lost.
+
+
Go back to the editor and correct the error(s). This is achieved
+ by clicking No.
+
+
Create a backup of your VHDL code and close the editor. This is
+ achieved by clicking the Create backup button, and then
+ by selecting a folder and a name for your backup file.
+
+
+
+
Using a VHDL entity
+
+
A VHDL entity is used like any other component. The only notable
+ difference is how the entities are handled in the simulation. Please
+ see VHDL simulator for a detailed
+ explanation.
+
+ Logisim-evolution is an educational tool for designing and simulating digital logic circuits. With its simple toolbar interface and simulation of circuits as they are built, it is simple enough to facilitate learning the most basic concepts related to logic circuits. With the capacity to build larger circuits from smaller subcircuits, and to draw bundles of wires with a single mouse drag, Logisim can be used (and is used) to design and simulate entire CPUs for educational purposes.
+
+
+ Students at colleges and universities around the world use Logisim for a variety of purposes, including:
+
+
+
A module in general-education computer science surveys
+
+
A unit in sophomore-level computer organization courses
+
+
Over a full semester in upper-division computer architecture courses
+
+
+
+ The Guide to Being a Logisim User, which you are reading now, is the official reference for Logisim's features. Its first part is a sequence of sections introducing the major parts of Logisim. These sections are written so that they can be read "cover to cover" to learn about all of the most important features of Logisim.
+
+ This orientation to the Logisim libraries concludes with a fairly sophisticated Gray code counter that allows the user to alter its current value using the Poke Tool and to place a label on the component using the Text Tool. It also customizes the icon that appears in the explorer, associated with the tool.
+
+
+ GrayCounter
+
+
package com.cburch.gray;
+
+import java.net.URL;
+
+import javax.swing.ImageIcon;
+
+import com.cburch.logisim.data.Attribute;
+import com.cburch.logisim.data.BitWidth;
+import com.cburch.logisim.data.Bounds;
+import com.cburch.logisim.data.Direction;
+import com.cburch.logisim.instance.Instance;
+import com.cburch.logisim.instance.InstanceFactory;
+import com.cburch.logisim.instance.InstancePainter;
+import com.cburch.logisim.instance.InstanceState;
+import com.cburch.logisim.instance.Port;
+import com.cburch.logisim.instance.StdAttr;
+import com.cburch.logisim.util.GraphicsUtil;
+import com.cburch.logisim.util.StringUtil;
+
+/** Manufactures a counter that iterates over Gray codes. This demonstrates
+ * several additional features beyond the SimpleGrayCounter class. */
+class GrayCounter extends InstanceFactory {
+ public GrayCounter() {
+ super("Gray Counter");
+ setOffsetBounds(Bounds.create(-30, -15, 30, 30));
+ setPorts(new Port[] {
+ new Port(-30, 0, Port.INPUT, 1),
+ new Port( 0, 0, Port.OUTPUT, StdAttr.WIDTH),
+ });
+
+ // We'll have width, label, and label font attributes. The latter two
+ // attributes allow us to associate a label with the component (though
+ // we'll also need configureNewInstance to configure the label's
+ // location).
+ setAttributes(
+ new Attribute[] { StdAttr.WIDTH, StdAttr.LABEL, StdAttr.LABEL_FONT },
+ new Object[] { BitWidth.create(4), "", StdAttr.DEFAULT_LABEL_FONT });
+
+ // The following method invocation sets things up so that the instance's
+ // state can be manipulated using the Poke Tool.
+ setInstancePoker(CounterPoker.class);
+
+ // These next two lines set it up so that the explorer window shows a
+ // customized icon representing the component type. This should be a
+ // 16x16 image.
+ URL url = getClass().getClassLoader().getResource("com/cburch/gray/counter.gif");
+ if(url != null) setIcon(new ImageIcon(url));
+ }
+
+ /** The configureNewInstance method is invoked every time a new instance
+ * is created. In the superclass, the method doesn't do anything, since
+ * the new instance is pretty thoroughly configured already by default. But
+ * sometimes you need to do something particular to each instance, so you
+ * would override the method. In this case, we need to set up the location
+ * for its label. */
+ protected void configureNewInstance(Instance instance) {
+ Bounds bds = instance.getBounds();
+ instance.setTextField(StdAttr.LABEL, StdAttr.LABEL_FONT,
+ bds.getX() + bds.getWidth() / 2, bds.getY() - 3,
+ GraphicsUtil.H_CENTER, GraphicsUtil.V_BASELINE);
+ }
+
+ public void propagate(InstanceState state) {
+ // This is the same as with SimpleGrayCounter, except that we use the
+ // StdAttr.WIDTH attribute to determine the bit width to work with.
+ BitWidth width = state.getAttributeValue(StdAttr.WIDTH);
+ CounterData cur = CounterData.get(state, width);
+ boolean trigger = cur.updateClock(state.getPort(0));
+ if(trigger) cur.setValue(GrayIncrementer.nextGray(cur.getValue()));
+ state.setPort(1, cur.getValue(), 9);
+ }
+
+ public void paintInstance(InstancePainter painter) {
+ // This is essentially the same as with SimpleGrayCounter, except for
+ // the invocation of painter.drawLabel to make the label be drawn.
+ painter.drawBounds();
+ painter.drawClock(0, Direction.EAST);
+ painter.drawPort(1);
+ painter.drawLabel();
+
+ if(painter.getShowState()) {
+ BitWidth width = painter.getAttributeValue(StdAttr.WIDTH);
+ CounterData state = CounterData.get(painter, width);
+ Bounds bds = painter.getBounds();
+ GraphicsUtil.drawCenteredText(painter.getGraphics(),
+ StringUtil.toHexString(width.getWidth(), state.getValue().toIntValue()),
+ bds.getX() + bds.getWidth() / 2,
+ bds.getY() + bds.getHeight() / 2);
+ }
+ }
+}
+
+
+ CounterPoker
+
+
package com.cburch.gray;
+
+import java.awt.Color;
+import java.awt.Graphics;
+import java.awt.event.KeyEvent;
+import java.awt.event.MouseEvent;
+
+import com.cburch.logisim.data.BitWidth;
+import com.cburch.logisim.data.Bounds;
+import com.cburch.logisim.data.Value;
+import com.cburch.logisim.instance.InstancePainter;
+import com.cburch.logisim.instance.InstancePoker;
+import com.cburch.logisim.instance.InstanceState;
+import com.cburch.logisim.instance.StdAttr;
+
+/** When the user clicks a counter using the Poke Tool, a CounterPoker object
+ * is created, and that object will handle all user events. Note that
+ * CounterPoker is a class specific to GrayCounter, and that it must be a
+ * subclass of InstancePoker in the com.cburch.logisim.instance package. */
+public class CounterPoker extends InstancePoker {
+ public CounterPoker() { }
+
+ /** Determines whether the location the mouse was pressed should result
+ * in initiating a poke.
+ */
+ public boolean init(InstanceState state, MouseEvent e) {
+ return state.getInstance().getBounds().contains(e.getX(), e.getY());
+ // Anywhere in the main rectangle initiates the poke. The user might
+ // have clicked within a label, but that will be outside the bounds.
+ }
+
+ /** Draws an indicator that the caret is being selected. Here, we'll draw
+ * a red rectangle around the value. */
+ public void paint(InstancePainter painter) {
+ Bounds bds = painter.getBounds();
+ BitWidth width = painter.getAttributeValue(StdAttr.WIDTH);
+ int len = (width.getWidth() + 3) / 4;
+
+ Graphics g = painter.getGraphics();
+ g.setColor(Color.RED);
+ int wid = 7 * len + 2; // width of caret rectangle
+ int ht = 16; // height of caret rectangle
+ g.drawRect(bds.getX() + (bds.getWidth() - wid) / 2,
+ bds.getY() + (bds.getHeight() - ht) / 2, wid, ht);
+ g.setColor(Color.BLACK);
+ }
+
+ /** Processes a key by just adding it onto the end of the current value. */
+ public void keyTyped(InstanceState state, KeyEvent e) {
+ // convert it to a hex digit; if it isn't a hex digit, abort.
+ int val = Character.digit(e.getKeyChar(), 16);
+ BitWidth width = state.getAttributeValue(StdAttr.WIDTH);
+ if(val < 0 || (val & width.getMask()) != val) return;
+
+ // compute the next value
+ CounterData cur = CounterData.get(state, width);
+ int newVal = (cur.getValue().toIntValue() * 16 + val) & width.getMask();
+ Value newValue = Value.createKnown(width, newVal);
+ cur.setValue(newValue);
+ state.fireInvalidated();
+
+ // You might be tempted to propagate the value immediately here, using
+ // state.setPort. However, the circuit may currently be propagating in
+ // another thread, and invoking setPort directly could interfere with
+ // that. Using fireInvalidated notifies the propagation thread to
+ // invoke propagate on the counter at its next opportunity.
+ }
+}
+
+ Beyond the sequence of examples provided here, the Logisim source code provides copious additional examples, though they do not always illustrate the same attention to readability and good design.
+
+
+ For maximum portability to future versions, you should stick as much as possible to the classes in the ...instance, ...data, and ...tools packages. Of course, you may use other packages' APIs, but they are more vulnerable to changes in future versions of Logisim.
+
+
+ I am generally willing to answer occasional requests for help. And bug reports and suggestions for improvements, of course, are always welcome.
+
+
+ Distribution
+
+
+ You are free to distribute any JARs you develop without restriction. The GPL restrictions do apply, however, if portions of your work are derived from portions of Logisim source code (released under the GPL). Deriving from the example code in this section of the User's Guide does not incur such restrictions; these examples are released under the MIT license.
+
+
+ If you would like to share your library with other Logisim users, I will be happy to provide a link to a hosting Web page or the JAR file itself through the Logisim Web site. If you think your library should be built into the basic Logisim release, then I welcome your suggestion, and I'll be happy to acknowledge your contribution in Logisim releases including the work.
+
+ Each component included in a library is defined by creating a subclass of InstanceFactory found in the com.cburch.logisim.instance package. This subclass has all the code involved
+
+
+ (Here we're describing the API for the current version of Logisim. You may find some libraries developed for older versions of Logisim, in which components were developed by defining two classes, one extending Component and another extending ComponentFactory. Version 2.3.0 introduced the much simpler InstanceFactory API; the older technique is deprecated.)
+
+
+ Three Logisim packages define most of the classes relevant to defining component libraries.
+
+
+
+ com.cburch.logisim.instance
+
+
+
+ Contains classes specifically related to defining components, including the InstanceFactory, InstanceState, InstancePainter, and Instance classes.
+
+
+
+ com.cburch.logisim.data
+
+
+
+ Contains classes related to data elements associated with components, such as the Bounds class for representing bounding rectangles or the Value class for representing values that can exist on a wire.
+
+
+
+ com.cburch.logisim.tools
+
+
+
+ Contains classes related to the library definition.
+
+
+
+
+ About Gray codes
+
+
+ Before we go on, let me briefly describe the Gray code on which these examples are based. It's not really important to understanding how these examples work, so you can safely skip to the code below if you wish - particularly if you already know Gray codes.
+
+
+ Gray code is a technique (named after Frank Gray) for iterating through n-bit sequences with only one bit changed for each step. As an example, consider the 4-bit Gray code listed below.
+
+
+
+
+
+
+ 0000
+ 0001
+ 0011
+ 0010
+
+
+
+
+
+ 0110
+ 0111
+ 0101
+ 0100
+
+
+
+
+
+ 1100
+ 1101
+ 1111
+ 1110
+
+
+
+
+
+ 1010
+ 1011
+ 1001
+ 1000
+
+
+
+
+
+
+ Each value has the bit underlined that will change for the next value in the sequence. For example, after 0000 comes 0001, in which the final bit has been toggled, so the final bit is underlined.
+
+
+ Logisim's built-in components don't include anything working with Gray codes. But electronics designers find Gray codes useful sometimes. One particularly notable instance of Gray codes is along the axes in Karnaugh maps.
+
+
+ GrayIncrementer
+
+
+ This is a minimal example illustrating the essential elements to defining a component. This particular component is an incrementer, which takes an multibit input and produces the next Gray code following it in sequence.
+
+
package com.cburch.gray;
+
+import com.cburch.logisim.data.Attribute;
+import com.cburch.logisim.data.BitWidth;
+import com.cburch.logisim.data.Bounds;
+import com.cburch.logisim.data.Value;
+import com.cburch.logisim.instance.InstanceFactory;
+import com.cburch.logisim.instance.InstancePainter;
+import com.cburch.logisim.instance.InstanceState;
+import com.cburch.logisim.instance.Port;
+import com.cburch.logisim.instance.StdAttr;
+
+/** This component takes a multibit input and outputs the value that follows it
+ * in Gray Code. For instance, given input 0100 the output is 1100. */
+class GrayIncrementer extends InstanceFactory {
+ /* Note that there are no instance variables. There is only one instance of
+ * this class created, which manages all instances of the component. Any
+ * information associated with individual instances should be handled
+ * through attributes. For GrayIncrementer, each instance has a "bit width"
+ * that it works with, and so we'll have an attribute. */
+
+ /** The constructor configures the factory. */
+ GrayIncrementer() {
+ super("Gray Code Incrementer");
+
+ /* This is how we can set up the attributes for GrayIncrementers. In
+ * this case, there is just one attribute - the width - whose default
+ * is 4. The StdAttr class defines several commonly occurring
+ * attributes, including one for "bit width." It's best to use those
+ * StdAttr attributes when appropriate: A user can then select several
+ * components (even from differing factories) with the same attribute
+ * and modify them all at once. */
+ setAttributes(new Attribute[] { StdAttr.WIDTH },
+ new Object[] { BitWidth.create(4) });
+
+ /* The "offset bounds" is the location of the bounding rectangle
+ * relative to the mouse location. Here, we're choosing the component to
+ * be 30x30, and we're anchoring it relative to its primary output
+ * (as is typical for Logisim), which happens to be in the center of the
+ * east edge. Thus, the top left corner of the bounding box is 30 pixels
+ * west and 15 pixels north of the mouse location. */
+ setOffsetBounds(Bounds.create(-30, -15, 30, 30));
+
+ /* The ports are locations where wires can be connected to this
+ * component. Each port object says where to find the port relative to
+ * the component's anchor location, then whether the port is an
+ * input/output/both, and finally the expected bit width for the port.
+ * The bit width can be a constant (like 1) or an attribute (as here).
+ */
+ setPorts(new Port[] {
+ new Port(-30, 0, Port.INPUT, StdAttr.WIDTH),
+ new Port(0, 0, Port.OUTPUT, StdAttr.WIDTH),
+ });
+ }
+
+ /** Computes the current output for this component. This method is invoked
+ * any time any of the inputs change their values; it may also be invoked in
+ * other circumstances, even if there is no reason to expect it to change
+ * anything. */
+ public void propagate(InstanceState state) {
+ // First we retrieve the value being fed into the input. Note that in
+ // the setPorts invocation above, the component's input was included at
+ // index 0 in the parameter array, so we use 0 as the parameter below.
+ Value in = state.getPort(0);
+
+ // Now compute the output. We've farmed this out to a helper method,
+ // since the same logic is needed for the library's other components.
+ Value out = nextGray(in);
+
+ // Finally we propagate the output into the circuit. The first parameter
+ // is 1 because in our list of ports (configured by invocation of
+ // setPorts above) the output is at index 1. The second parameter is the
+ // value we want to send on that port. And the last parameter is its
+ // "delay" - the number of steps it will take for the output to update
+ // after its input.
+ state.setPort(1, out, out.getWidth() + 1);
+ }
+
+ /** Says how an individual instance should appear on the canvas. */
+ public void paintInstance(InstancePainter painter) {
+ // As it happens, InstancePainter contains several convenience methods
+ // for drawing, and we'll use those here. Frequently, you'd want to
+ // retrieve its Graphics object (painter.getGraphics) so you can draw
+ // directly onto the canvas.
+ painter.drawRectangle(painter.getBounds(), "G+1");
+ painter.drawPorts();
+ }
+
+ /** Computes the next gray value in the sequence after prev. This static
+ * method just does some bit twiddling; it doesn't have much to do with
+ * Logisim except that it manipulates Value and BitWidth objects. */
+ static Value nextGray(Value prev) {
+ BitWidth bits = prev.getBitWidth();
+ if(!prev.isFullyDefined()) return Value.createError(bits);
+ int x = prev.toIntValue();
+ int ct = (x >> 16) ^ x; // compute parity of x
+ ct = (ct >> 8) ^ ct;
+ ct = (ct >> 4) ^ ct;
+ ct = (ct >> 2) ^ ct;
+ ct = (ct >> 1) ^ ct;
+ if((ct & 1) == 0) { // if parity is even, flip 1's bit
+ x = x ^ 1;
+ } else { // else flip bit just above last 1
+ int y = x ^ (x & (x - 1)); // first compute the last 1
+ y = (y << 1) & bits.getMask();
+ x = (y == 0 ? 0 : x ^ y);
+ }
+ return Value.createKnown(bits, x);
+ }
+}
+
+
+ This example by itself is not enough to create a working JAR file; you must also provide a Library class, as illustrated on the next page.
+
+ Logisim has two types of circuit components: those that are designed within Logisim as combinations of components, and those primitive components that are written in Java. Logisim circuits are easier to design, but they cannot support sophisticated user interaction, and they are relatively inefficient.
+
+
+ Logisim contains a fairly thorough collection of built-in libraries of Java components, but it can also load additional libraries written by you or others. Once you have downloaded a library, you can import it into your project by right-clicking the project in the explorer pane (the top line) and choosing Load Library > JAR Library.... Then, Logisim will prompt you to select the JAR file. (In some circumstances, you may have to type the starting class name when prompted, which would be provided by the library developer. However, a developer typically configures the JAR library to avoid this (by including a manifest file in the JAR with a Library-Class attribute specifying the main class name).)
+
+
+ Creating JAR libraries
+
+
+ The remainder of this section is dedicated to a series of thoroughly commented examples illustrating how to develop Logisim libraries yourself. You should only attempt this if you're an experienced Java programmer. You will find the documentation beyond these examples fairly meager.
+
+
+ You can download a JAR file that allows these examples to be imported into Logisim via the Logisim Web site's Links section. That JAR file also contains the source code contained in these examples.
+
+ Illustrates the essential components of any component type using a simple example of a component that takes a multibit input and computes the next Gray code value following it.
+
+ Demonstrates a complete, fairly sophisticated component with which the user can interact. It implements a Gray code counter where the number of bits remembered is customizable, and where the user can edit the current value by clicking on it with the Poke Tool and typing a value.
+
+ General information for those developing third-party libraries.
+
+
+
+ License
+
+
+ The code in this example JAR library is released under the MIT license, a more permissive license than the GPL, under which the rest of Logisim is released.
+
+
+ Copyright (c) 2009, Carl Burch.
+
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ The access point for the JAR library is a class that extends the Library class. The library's main job is to list the tools that are available through the library; most often, the tools are all tools to add the various components defined - that is, instances of the AddTool class working with different component factories.
+
+
+ Components
+
+
package com.cburch.gray;
+
+import java.util.Arrays;
+import java.util.List;
+
+import com.cburch.logisim.tools.AddTool;
+import com.cburch.logisim.tools.Library;
+
+/** The library of components that the user can access. */
+public class Components extends Library {
+ /** The list of all tools contained in this library. Technically,
+ * libraries contain tools, which is a slightly more general concept
+ * than components; practically speaking, though, you'll most often want
+ * to create AddTools for new components that can be added into the circuit.
+ */
+ private List<AddTool> tools;
+
+ /** Constructs an instance of this library. This constructor is how
+ * Logisim accesses first when it opens the JAR file: It looks for
+ * a no-arguments constructor method of the user-designated class.
+ */
+ public Components() {
+ tools = Arrays.asList(new AddTool[] {
+ new AddTool(new GrayIncrementer()),
+ new AddTool(new SimpleGrayCounter()),
+ new AddTool(new GrayCounter()),
+ });
+ }
+
+ /** Returns the name of the library that the user will see. */
+ public String getDisplayName() {
+ return "Gray Tools";
+ }
+
+ /** Returns a list of all the tools available in this library. */
+ public List<AddTool> getTools() {
+ return tools;
+ }
+}
+
+ Often we want components that aren't exclusively combinational in nature - that is, we want the component to have some memory. There is an important subtlety in defining such components: You can't have the component itself store the state, because an individual component can appear many times in the same circuit. It can't appear directly within a circuit multiple times, but it can appear multiple times if it appears in a subcircuit that is used several times.
+
+
+ The solution is to create a new class for representing the object's current state, and to associate instances of this with the component through the parent circuit's state. In this example, which implements an edge-triggered 4-bit Gray code counter, we define a CounterData class to represent the counter's state, in addition to the InstanceFactory subclass as illustrated previously. The CounterData object remembers both the counter's current value, as well as the last clock input seen (to detect rising edges).
+
+
+ CounterData
+
+
package com.cburch.gray;
+
+import com.cburch.logisim.data.BitWidth;
+import com.cburch.logisim.data.Value;
+import com.cburch.logisim.instance.InstanceData;
+import com.cburch.logisim.instance.InstanceState;
+
+/** Represents the state of a counter. */
+class CounterData implements InstanceData, Cloneable {
+ /** Retrieves the state associated with this counter in the circuit state,
+ * generating the state if necessary.
+ */
+ public static CounterData get(InstanceState state, BitWidth width) {
+ CounterData ret = (CounterData) state.getData();
+ if(ret == null) {
+ // If it doesn't yet exist, then we'll set it up with our default
+ // values and put it into the circuit state so it can be retrieved
+ // in future propagations.
+ ret = new CounterData(null, Value.createKnown(width, 0));
+ state.setData(ret);
+ } else if(!ret.value.getBitWidth().equals(width)) {
+ ret.value = ret.value.extendWidth(width.getWidth(), Value.FALSE);
+ }
+ return ret;
+ }
+
+ /** The last clock input value observed. */
+ private Value lastClock;
+
+ /** The current value emitted by the counter. */
+ private Value value;
+
+ /** Constructs a state with the given values. */
+ public CounterData(Value lastClock, Value value) {
+ this.lastClock = lastClock;
+ this.value = value;
+ }
+
+ /** Returns a copy of this object. */
+ public Object clone() {
+ // We can just use what super.clone() returns: The only instance variables are
+ // Value objects, which are immutable, so we don't care that both the copy
+ // and the copied refer to the same Value objects. If we had mutable instance
+ // variables, then of course we would need to clone them.
+ try { return super.clone(); }
+ catch(CloneNotSupportedException e) { return null; }
+ }
+
+ /** Updates the last clock observed, returning true if triggered. */
+ public boolean updateClock(Value value) {
+ Value old = lastClock;
+ lastClock = value;
+ return old == Value.FALSE && value == Value.TRUE;
+ }
+
+ /** Returns the current value emitted by the counter. */
+ public Value getValue() {
+ return value;
+ }
+
+ /** Updates the current value emitted by the counter. */
+ public void setValue(Value value) {
+ this.value = value;
+ }
+}
+
+
+ SimpleCounter
+
+
package com.cburch.gray;
+
+import com.cburch.logisim.data.BitWidth;
+import com.cburch.logisim.data.Bounds;
+import com.cburch.logisim.data.Direction;
+import com.cburch.logisim.instance.InstanceFactory;
+import com.cburch.logisim.instance.InstancePainter;
+import com.cburch.logisim.instance.InstanceState;
+import com.cburch.logisim.instance.Port;
+import com.cburch.logisim.util.GraphicsUtil;
+import com.cburch.logisim.util.StringUtil;
+
+/** Manufactures a simple counter that iterates over the 4-bit Gray Code. This
+ * example illustrates how a component can maintain its own internal state. All
+ * of the code relevant to state, though, appears in CounterData class. */
+class SimpleGrayCounter extends InstanceFactory {
+ private static final BitWidth BIT_WIDTH = BitWidth.create(4);
+
+ // Again, notice how we don't have any instance variables related to an
+ // individual instance's state. We can't put that here, because only one
+ // SimpleGrayCounter object is ever created, and its job is to manage all
+ // instances that appear in any circuits.
+
+ public SimpleGrayCounter() {
+ super("Gray Counter (Simple)");
+ setOffsetBounds(Bounds.create(-30, -15, 30, 30));
+ setPorts(new Port[] {
+ new Port(-30, 0, Port.INPUT, 1),
+ new Port( 0, 0, Port.OUTPUT, BIT_WIDTH.getWidth()),
+ });
+ }
+
+ public void propagate(InstanceState state) {
+ // Here I retrieve the state associated with this component via a helper
+ // method. In this case, the state is in a CounterData object, which is
+ // also where the helper method is defined. This helper method will end
+ // up creating a CounterData object if one doesn't already exist.
+ CounterData cur = CounterData.get(state, BIT_WIDTH);
+
+ boolean trigger = cur.updateClock(state.getPort(0));
+ if(trigger) cur.setValue(GrayIncrementer.nextGray(cur.getValue()));
+ state.setPort(1, cur.getValue(), 9);
+
+ // (You might be tempted to determine the counter's current value
+ // via state.getPort(1). This is erroneous, though, because another
+ // component may be pushing a value onto the same point, which would
+ // "corrupt" the value found there. We really do need to store the
+ // current value in the instance.)
+ }
+
+ public void paintInstance(InstancePainter painter) {
+ painter.drawBounds();
+ painter.drawClock(0, Direction.EAST); // draw a triangle on port 0
+ painter.drawPort(1); // draw port 1 as just a dot
+
+ // Display the current counter value centered within the rectangle.
+ // However, if the context says not to show state (as when generating
+ // printer output), then skip this.
+ if(painter.getShowState()) {
+ CounterData state = CounterData.get(painter, BIT_WIDTH);
+ Bounds bds = painter.getBounds();
+ GraphicsUtil.drawCenteredText(painter.getGraphics(),
+ StringUtil.toHexString(BIT_WIDTH.getWidth(), state.getValue().toIntValue()),
+ bds.getX() + bds.getWidth() / 2,
+ bds.getY() + bds.getHeight() / 2);
+ }
+ }
+}
+
The File tab allows you to specify a file into which the log should
+be placed.
+
+
+
+
At the top is an indicator of whether file logging is in progress and
+a button for enabling or disabling it. (Note that you cannot enable it
+until a file is selected below.) The button allows you to pause and
+restart file entry. When you switch in the project window to viewing
+another simulation, the file logging is automatically halted; if you
+return to the original one and want logging to continue, you will need
+to re-enable the file logging manually using the button at top.
+
+
In the middle is an indicator of what file is being logged to. To
+change it, use the Select... button. On selecting a file, file logging
+will automatically start. If you select a pre-existing file, Logisim
+will ask whether you want to overwrite the file or append the new
+entries onto the end.
+
+
At bottom you can control whether a header line should be placed into
+the file indicating which items are in the selection. If header lines
+are added, then a new header line will be placed into the file whenever
+the selection changes.
+
+
File format
+
+
Entries are placed into the file in tab-delimited format
+corresponding closely to what appears under the Table tab. (One
+difference is that any header lines will give the full path to
+components lying in subcircuits.) The format is intentionally simple so
+that you can feed it into another program for processing, such as a
+Python/Perl script or a spreadsheet program.
+
+
So that a script can process the file at the same time as Logisim
+is running, Logisim will flush the new records onto the disk every
+500 ms. Note that Logisim may also intermittently close and later
+re-open the file during the simulation, particularly if several seconds
+have elapsed without any new records being added.
The Table tab displays the current log graphically.
+
+
+
+
The table contains a column for each component in the selection. Each
+row in the table displays a snapshot of the simulation after a
+propagation of values has completed. Any duplicate rows are not added
+into the log. Note that only the most recent 400 rows are displayed.
+Some rows may have empty entries if the corresponding component was not
+in the selection at the time that the row was computed.
+
+
The displayed table is for review only; it is not interactive.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/log/_test.html b/src/main/resources/doc/en/html/guide/log/_test.html
new file mode 100644
index 0000000000..d39f870f7d
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/log/_test.html
@@ -0,0 +1,71 @@
+
+
+
+
+
+
+
+
+ The Test Vector window
+
+
+
+
The Test Vector window
+
+
The Test Vector window is similar to the Table tab of the Logging
+window. You can load a test vector from a file, and Logisim will start
+running tests on the current circuit. Like the logging window, there
+is only one test vector window for the project, and the table will
+change to reflect whichever circuit is being simulated in the project
+window. Note, however, that the Test Vector module runs a separate
+copy of the circuit simulator, and so does not interfere with, and is
+not influenced by, the simulation in the project window.
+
+
Any incorrect outputs will be flagged in red. Hover the mouse over
+the red box to see what the output should have been, according to the
+test vector. Rows with incorrect outputs are sorted to the top of the
+window.
+
+
The file format is simple. You can use the Logging module (with
+"Include Header Line" selected in the file output tab) to get started,
+since in most cases the Logging module outputs the same format as used
+by the Test Vector module.
+
+
Here is an example test vector file:.
+
+# my test vector for add32
+A[32] B[32] C[32] Cin Cout
+00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 0 0
+-2 0x00000005 3 0 0
+0 0o0003 3 0 0
+
+
+
+
Blank lines are ignored. Anything following a '#' character is a
+comment. The first non-blank, non-comment line lists the name of each
+circuit input pin and its width (if > 1), separated by whitespace.
+
+
+
The remaining lines list each value separated by whitespace. The
+values can be in hex, octal, binary, or signed decimal. Hex values
+must have a '0x' prefix. Octal values must have a '0o' prefix.
+Binary and decimal are be
+distinguished by the number of digits: binary values must always have
+exactly as many digits as the width of the column; decimal values must
+always have fewer, should not have leading zeros, and may have a
+negative sign.
+
+
For hex, octal, and binary values, a digit of 'x' specifies four,
+three, or one "don't care" bits. So the value 101xx is a five bit
+binary value, with the last two bits unspecified, and 0x1ax5 is a hex
+value with four unspecified bits. Such "don't cares" can not be used
+in decimal notation.
+
+
Command line: To facilitate automated testing, the
+test vector feature can be run from the command line, as follows:
+logisim -test <circuitname> <vector.txt> <project.circ>
+ To understand or debug a circuit it is often very useful to be able to observe the different signals in a visual way. This is the purpose of the timeline. This module allows the recording of signals in graphical form or in a table of value in a text file.
+
+
+
+
+
+ You can enter the logging module via the menu | Simulate |→| Chronogram |. It brings up the signal selection window.
+
+
+ The circuit below is an illustrative example for the timing module.
+
+
+
+
+
+ These are the clocks that serve as a driver for displaying signals. The simulation knows two particular clocks. One is imperative and named sysclk and another optional and secondary named clk
+
+
+ Note: it is imperative that a clock named sysclk appears in your circuit. It will be used as a time base by the chronogram module. It does not have to be connected to your circuit. It is in principle the fastest and is set to a duty cycle 1/1 tic.
+
+ The Selection tab allows you to select which values should be included in the log. The window below corresponds to the following circuit.
+
+
+
+
+
+
+
+
+ The tab is divided into three vertical areas. The first (leftmost) is a list of all components in the circuit whose values can be logged. Among the built-in libraries, the following types of components support logging.
+
+
+ Wiring library: Pin, Probe, and Clock components
+ I/O library: Button and LED components
+ Memory library: All components except ROM
+
For components which have labels associated with them, their names correspond to the labels; other components' names specify their type and their location within the circuit.
+ Any subcircuits will also appear in the list; they cannot be selected for logging, but eligible components within them can be. Note that the RAM component requires you to choose which memory address(es) should be logged; it allows logging only for the first 256 addresses.
+
+ The last (rightmost) vertical area lists those components that have been selected. Also, it indicates the radix (base) in which the component's multi-bit values will be logged; the radix does not have a significant effect on one-bit values.
+
+
+ L'horloge sysclk doit y figurer, elle ne sera pas affichée dans le graphe.
+
+
+ The middle column of buttons allows the manipulation of the items within the selection.
+
+
+
+ Add>> adds the currently selected item(s) on the left side into the selection. Il est actif seulement pour les composants éligibles.
+
+
+ Change Radix cycles the radix for the currently selected component in the selection between 2 (binary), 10 (decimal), and 16 (hexadecimal).
+
+
+ Move Up moves the currently selected component in the selection forward one spot.
+
+
+ Move Down moves the currently selected component in the selection back one spot.
+
+
+ << Remove removes the currently selected component in the selection.
+
+
+
+ The fourth part below allows you to define if you want a time display above the graph. For this it is necessary to check the box "Time reference" and select the signal that will be the reference. The frequency will define the displayed time scale. This does not solve the speed of execution of the circuit simulation. For example below we have selected the signal B0 and a frequency of 100hz.
+
+ This window allows the display of the chronograms of the previously selected signals. You will notice the menu, the toolbar, two display areas and the buttons.
+
+
+
+
+
+ The | windows | menu contains only one option to specify whether the window remains displayed above the others or whether it can go in the background. By default it stays above.
+
+
+ The toolbar has five buttons
+
+
+
+
+
+
+
+
+
+
+
+
+ Allows to activate the simulation or stop. Equivalent of the | Simulate || Simulation Enabled | menu.
+
+
+
+
+
+
+
+
+
+
+ Advance a tick in the simulation. Equivalent of the | Simulate || Tick Once | menu.
+
+
+
+
+
+
+
+
+
+
+ Enable or disable the sysclk clock. Equivalent of the | Simulate || Ticks Enabled | menu.
+
+
+
+
+
+
+
+
+
+
+ half a period advance the clock sysclk. Equivalent of the | Simulate || Tick Once | menu.
+
+
+
+
+
+
+
+
+ Advancing a period or half-period the clock clk. Equivalent of the | Simulate || 'Clk' Tick Once | menu.
+
+
+
+
+
+
+ The display areaOn the right three columns: the first presents an icon of the type of signal (bus or singlle) then we have the name and finally the signal value under the cursor (the red line in the graph). It is possible to move the cursor with the mouse, just click and move. Right-clicking on the row of a bus-type signal displays a pop-up menu with two options:
+
+
+
+ | Format | This menu opens a selection of the signal display base (binary, hexadecimal, octal, signed, unsigned)
+
+
+ | Expand | Display, below, the chronogram of each signal.
+
+
+
+ Buttons: There are three buttons at the bottom of our window.
+
+
+
+ Load file Loads and displays the result from a previously saved file. This does not allow to set the simulation.
+
+
+ Export... Exports the data into a text file. You will need to specify the file name in the select window. The file format is easy. The first line contains the names of the columns separated by a tab. The second line shows the signal and time scale if selected. The following lines show the value of its signals separated by a tab. The third line is the initialization and then each line represents a half-period of the clock sysclk.
+
+ The RAM and ROM components are two of the more useful components in Logisim's built-in libraries. However, because of the volume of information they can store, they are also two of the most complex components.
+
+
+ Documentation about how they work within a circuit can be found on the RAM and ROM pages of the Library Reference. This section of the User's Guide explains the interface allowing the user to view and edit memory contents.
+
+ This window opens when the file recognition fails to determine the type of the data structure. It consists of a series of checkboxes to specify the conversion options. Two hexadecimal display tabs that show the file data and a text box that displays any errors that may have been detected.
+
+
+
+
+
+ The four radio buttons are used to select one of the file structure types shown above. For each type checkboxes will be activated. They allow you to specify specific options.
+ You will find information in the pages dedicated to these types
+
+ Logisim includes an integrated hex editor for viewing and editing the contents of memory. To access it, bring up a pop-up menu for the memory component (Right-click on the component ) and select | Edit Contents.... | or in the properties select Contents.
+
+
+
+
+
+ The numbers in italics at left display memory addresses, written in hexadecimal. The other numbers display values starting from that memory address; the hex editor may display four, eight, or sixteen values per line, depending on what fits in the window. To help with counting, each group of four values has a larger space between./p>
+
+
+ You can navigate through memory using the scroll bar or using the keyboard (the arrow keys, home, end, page up, and page down). Typing hexadecimal characters will alter the currently selected value.
+
+
+ You can select a range of values by dragging the mouse, shift-clicking the mouse, or navigating through memory with the keyboard while depressing the shift key. Values may be copied and pasted using the | Edit | menu or the associated shortcuts key (Ctrl-C Ctrl-V,Ctrl-X...); the clipboard can also be transferred into other applications.
+
+
+ Two buttons (Open..., Save..) allow you to load or save data from a file.
+
+ The pop-up menu for memory includes four options in addition to the options common to all components:
+
+
+
+ Edit Contents:
+
+
+ Bring up a hex editor for editing the contents of memory.
+
+
+ Clear Contents:
+
+
+ Resets all values in memory to 0 and for RAM to 0 or randomly depending on the parameters in Project options .
+
+
+ Load Image...:
+
+
+ Resets all values in memory to the values found in a file. The file format is recognized automatically and if it is not the case a window Memory file panel opens for an appropriate selection.
+
+
+ Save Image...:
+
+
+ Stores all values in memory in a file using one of the formats described below.
+
+
+
+ File format
+
+
+
+ v2.0 raw Historical version of logisim allows "run.length" coding.
+
+ You can manipulate the contents of memory using the Poke Tool (), but the interface for this is severely limited by space constraints: For more than the simplest editing, you will probably find the integrated hex editor far more convenient.
+
+
+ Nonetheless, to view and edit values within the circuit, the Poke Tool has two modes of operation: You can edit the address displayed, and you can edit an individual value.
+
+
+ Address selection
+
+
+ To edit the address displayed, click outside the display rectangle. Logisim will draw a red rectangle around the top address.
+
+
+
+
+
+
+
+ Typing hexadecimal digits will change the top address accordingly.
+
+
+
+
+ Typing the Enter key will scroll down one line.
+
+
+
+
+ Typing the Backspace key will scroll up one line.
+
+
+
+
+ Typing the space bar will scroll down one page (four lines).
+
+
+
+
+ Modification of data
+
+
+ To edit a particular value, click the value within the display rectangle. Logisim will draw a red rectangle around that address.
+
+
+
+
+
+
+
+ Typing hexadecimal digits will change the value at the address currently being edited.
+
+
+
+
+ The Enter key or Ctrl+Down arrow ill scroll the cursor down one line.
+
+
+
+
+ The Backspace key or Ctrl+Left Arrow will scroll the cursor one cell backwards.
+
+
+
+
+ The Space key or Ctrl+right Arrow will scroll the cursor one cell forward.
+
+
+
+
+ The mouse wheel or Ctrl+up arrow, Ctrl+Down arrow moves the cursor up/down a line.
+
+ The file format used for image files is intentionally simple; this permits you to write a program, such as an assembler, that generates memory images that can then be loaded. For example if we had a memory as below:
+
+
+
+
+
+ and then all the values are at zero and the resultant file will be the following.
+
+
+
v2.0 raw
+12 22 45 67 12*80 23 a2 bb
+ce 4f 6a cc 45 7*cc 12 24
+
+
+ The first line identifies the file format used (currently, there is only one file format recognized "raw"). Subsequent values list the values in hexadecimal, starting from address 0; you can place several such values on the same line. If the data dimension of the file is smaller than the space in memory the remaining cells will not be changed.
+
+
+ The image file can use run-length encoding; for example, rather than list the value 80 twelve times in a row, the file can include 12*80. Notice than the number of repetitions is written in base 10. Files produced by Logisim will use run-length encoding for runs of at least four values.
+
+
+ You can place comments into the file by using the '#' symbol. All characters in the line from the '#' symbol will be ignored by Logisim.
+
+
+ If the length of the data set in the file is shorter than the memory space the remaining cells will be initialized to 0 for ROM and RAM according to the parameters in Project options, to 0 or randomly.
+
+
+ If the width of the memory word in bits is smaller than the width of the data words in the file. Excessively large bits will be ignored.
+
+ This file is structured as in previous versions, the first line indicates the type of structure and then the following lines represent the sequence of bits in the memory. They are in ASCII with only hexadecimal symbols (two digits) without the 0x tag.
+
+ The line returns of his not interpreted. With the exception of the first line, there are no layout rules. Spaces are ignored.
+
+
+ You can place comments in the file using the '#' symbol. All characters in the line starting with the '#' symbol will be ignored.
+
+
+ There is no need to specify the 0x prefix before the data, however if they exist they will simply be ignored.
+
+
+ If the length of the data set of the file is shorter than the memory space the remaining cells will be initialized to 0 for ROM and for RAM to 0 or randomly according to the parameters in Project options.
+
+
+
+
+
+ In the big-endian mode the memory is considered as a sequence of bytes regardless of the size of its words, with left to right the high bytes and then the low bytes. In the figure above, the hexadecimal signs are represented in their binary value in the blue/green area and it can be observed that the bytes of the file (top) are copied into the memory in sequence with examples for memories with 4bits, 7bits and 12bits words. Observe the alignment offset for words not multiple of 8 for example in the 7-bit word memory.
+
+
+
+ v3.0 hex byte plain little-endian
+
+
+
+ This format follows the same rules as previous formats. Unlike the reading direction, in the little-endian mode it is read from right to left.
+
+ In the little-endian mode the memory is considered as a sequence of bytes with from right to left the low low bits and then the high bits. In the figure above we can see that the bytes of the file (top) are copied into the memory in sequence with examples for memories with 4bits, 7bits and 12bits words. You can observe the alignment offset for example for the 7-bit word memory.
+
+
+
+ The same examples are displayed in the component.
+
+
+ v3.0 hex bytes addressed big-endian
+
+
+ this format is identical to the previous ones with the possibility to specify the address of the memory word or to start recording the data of the line.
+ This one is in hexadecimal followed by the character :.
+
+ In this example the 8 words at address 0x10 are not specified. These cells will be initialized to 0 and for RAM according to the parameters in Project options, to 0 or randomly.
+
+
+
+
+
+ v3.0 hex bytes addressed little-endian
+
+
+ This format is identical to the previous ones with the possibility to specify the address of the memory word or to start recording the data of the line.
+
+ The line returns of his not interpreted. With the exception of spaces and the first line, there are no layout rules.
+
+
+ You can place comments in the file using the '#' symbol. All characters in the line starting from the '#' symbol will be ignored by Logisim. A double space will have the same effect.
+
+
+ There is no need to specify the 0x prefix before the data, however if they exist they will simply be ignored.
+
+
+ If the words in the file are larger than the words in memory, the most significant bits will be ignored.
+
+
+ If the length of the file data set is shorter than the memory space the remaining cells will be initialized to 0 and for RAM according to the parameters in Project options, to 0 or randomly.
+
+
+
+ v3.0 hex words addressed
+
+
+ This format is identical to the previous one with the same characteristics. In addition, an indication of the address at the beginning of the lines. The address is given in hexadecimal followed by the character :
+
+ In this example the 8 words at address 0x10 are not specified. These cells will be initialized to 0 and for RAM according to the parameters in Project options, to 0 or randomly.
+
+ ASCII encoding with escape code, data will be recorded byte by byte except for non-printable and non-standard characters. Characters outside the range 0x20 - 0x7E will be ignored. For characters of this type you must use the hexadecimal escape code \x... or one of the common codes \0 \a \b \t \n \v \f \r.
+
+ In the big-endian mode the memory is considered as a sequence of bytes regardless of the size of its words, with left to right the high bytes and then the low bytes. You can find illustrations in v3.0 hex bytes addressed big-endian
+
+
+ Ascii byte escape little-endian
+
+
+ This format is identical to the previous one with the same characteristics. In the little-endian mode, the memory is considered as a sequence of bytes with from right to left the least significant bits and then the most significant bits. You can find illustrations in v3.0 hex bytes addressed little-endian
+
+ This format is a raw binary image of the memory data in a file. There are no headers, no comments, no coding. The file is probably not editable in a common text editor.
+ In the big-endian mode the memory is considered as a sequence of bytes regardless of the size of its words, with left to right the high bytes and then the low bytes. Illustrations can be found in v3.0 hex bytes addressed big-endian
+
+
+ Binary data little-endian
+
+
+ This format is identical to the previous one with the same characteristics.
+ In the little-endian mode, the memory is considered as a sequence of bytes with from right to left the least significant bits and then the most significant bits. Illustrations can be found in v3.0 hex bytes addressed little-endian
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/menu/edit.html b/src/main/resources/doc/en/html/guide/menu/edit.html
new file mode 100644
index 0000000000..164deaacb2
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/menu/edit.html
@@ -0,0 +1,147 @@
+
+
+
+
+
+
+
+
+
+ The Edit menu
+
+
+
+
+
+
+ The Edit menu
+
+
+
+ Undo XXCtrl-Z
+
+
+
+ Undoes the most recently completed action affecting how the circuit would be saved in a file. Note that this does not include changes to the circuit state (as with manipulations performed by the Poke Tool).
+
+
+
+ Redo XXCtrl-R
+
+
Redo the previous command.
+
+
+ CutCtrl-X
+
+
+
+ Removes the currently selected components from the circuit onto Logisim's clipboard.
+
+
+ Note: Logisim's clipboard is maintained separately from the clipboard for the overall system; as a result, cut/copy/paste will not work across different applications, even including other running copies of Logisim. If, however, you have multiple projects open under the same Logisim process, then you should be able to cut/copy/paste between them.
+
+
+
+ CopyCtrl-C
+
+
+
+ Copies the currently selected components in the circuit onto Logisim's clipboard. (See the note under the Cut menu item.)
+
+
+
+ PasteCtrl-V
+
+
+
+ Pastes the components on Logisim's clipboard into the current selection. (See the note under the Cut menu item.)
+
+
+ When you paste components, they will not immediately be dropped; instead, they will be drawn in light gray. They will not actually be ``dropped'' into the circuit until you either move the selection or change the selection so that the components are no longer in it.
+
+
+ The reason for this odd behavior is this: To be consistent with its other behavior, Logisim must immediately merge any wires as soon as they are dropped into a circuit; this merging process changes existing wires in the circuit. When you paste wires from the clipboard, however, you may want them to appear in a different location, and the changing inherent in the merging process would be against your wishes.
+
+
+
+ DeleteDel / Delete
+
+
+
+ Removes all components in the current selection from the circuit, without modifying the clipboard.
+
+
+
+ DuplicateCtrl-D
+
+
+
+ Creates a copy of all components in the current selection. This is like selecting Copy, then Paste, except that Duplicate doesn't modify or use the clipboard.
+
+
+
+ Select AllCtrl-A
+
+
+
+ Selects all components in the current circuit.
+
+
+
+ Raise SelectionCtrl+Up
+
+
+
+ This menu item is available only when editing a circuit's appearance. It raises the currently selected object(s) so that it is drawn (or they are drawn) on top of an object that currently overlaps the selection. If the selection is overlapped by several objects, it is raised only to be above the lowest one; select the menu item repeatedly until it is in the order it should be.
+
+
+ (Determining whether two arbitrary objects overlap is difficult. Logisim uses an algorithm of selecting several random points in each of the two objects and seeing if any point is also in the other object. Sometimes it will fail to detect an overlap if the overlap is small — say, less than 5% of either of the objects.)
+
+
+
+ Lower SelectionCtrl+Down
+
+
+
+ This menu item is available only when editing a circuit's appearance. It lowers the currently selected object(s) so that it is drawn (or they are drawn) below an object that the selection currently overlaps. If the selection overlaps several objects, it is lowered only to be below the highest one; select the menu item repeatedly until it is in the order it should be.
+
+
+
+ Raise To TopCtrl-Schift-Up
+
+
+
+ Available only when editing a circuit's appearance, this menu item raises the currently selected object(s) to be drawn on top of all other objects. (The anchor and the ports are exceptions — they are always on top.)
+
+
+
+ Lower To BottomCtrl-Schift-Down
+
+
+
+ Available only when editing a circuit's appearance, this menu item lowers the currently selected object(s) so that all other objects are drawn on top of them.
+
+
+
+ Add Vertex
+
+
+
+ Available only when editing a circuit's appearance and a point has been selected on a line, polyline, or polygon, this menu item inserts a new vertex onto the shape. Previous to insertion, the selected point is drawn as a diamond.
+
+
+
+ Remove Vertex
+
+
+
+ Available only when editing a circuit's appearance and an existing vertex has been selected on a polyline or polygon, this menu item removes the selected vertex. Previous to deletion, the selected vertex is drawn as a diamond within the square representing the vertex. Logisim will not permit removing a vertex on a polygon with only three vertices or on a polyline with only two vertices.
+
+ When you select | Export Image... |, Logisim displays a dialog box with four options.
+
+
+
+
+
Configuring Export
+
+
+ Circuits: A list where you can select one or more circuits that should be exported into image files. (Empty circuits are not displayed as options.)
+
+
+ Image Format: You can create PNG, GIF, JPEG, TikZ and SVG files. I would recommend PNG files: The GIF format is quite dated, and the JPEG format will introduce artifacts into the image, as the JPEG format is really meant for photographic images.
+
+
+ Scale Factor:You can scale the images as they are dumped into image files using this slider.
+
+
+ Printer View:Style of the image produced with either the stat information or only the schema.
+
+
+
+
+ This option is also available in "Print view:" in the export of circuits. This will change the display in the workspace.
+
+
+ After clicking OK, Logisim will display a file selection dialog box. If you have selected one circuit, select the file into which the image should be placed. If you have selected multiple circuits, select a directory where the files should be placed; Logisim will name the images based on the circuits' names (main.png, for example).
+
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/menu/file.html b/src/main/resources/doc/en/html/guide/menu/file.html
new file mode 100644
index 0000000000..3d3fa34f1c
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/menu/file.html
@@ -0,0 +1,111 @@
+
+
+
+
+
+
+
+
+
+ The File menu
+
+
+
+
+
Many menu items relate specifically to a currently opened project. But some Logisim windows (particularly the Combinational Analysis window and the Application Preferences window) are not associated with projects. For these windows, the project-specific menu items will be disabled.
+
+ When you choose | Print... |, Logisim displays a dialog box for configuring what is printed.
+
+
+
+
+
+ Configuration of the printing
+
+
+
+ Circuits: A list where you can select one or more circuits to be printed. (Empty circuits are not displayed as options.) Logisim will print one circuit per page. If the circuit is too large for the page, the image will be scaled down to fit.
+
+
+ Header: Text that should appear centered at the top of each page. The following substitutions will be made into the text.
+
+
+
+
+
+ %n
+
+
+ Name of circuit on page
+
+
+
+
+ %p
+
+
+ Page number
+
+
+
+
+ %P
+
+
+ Total page count
+
+
+
+
+ %%
+
+
+ A single percent sign ('%')
+
+
+
+
+
+
+
+ Rotate To Fit: If checked, then Logisim will rotate each circuit by 90 degrees when the circuit is too large to fit onto the page and it does not need to be scaled as small when rotated 90 degrees.
+
+
+ Printer View: Whether to use "printer view" in printing the circuits.
+
+
+
+
+ This option is also available in "Print view:" in the export of circuits. This will change the display in the workspace.
+
+
+ After clicking OK , Logisim will display the standard page setup dialog box before printing the circuits.
+
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/menu/project.html b/src/main/resources/doc/en/html/guide/menu/project.html
new file mode 100644
index 0000000000..32b59464bf
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/menu/project.html
@@ -0,0 +1,189 @@
+
+
+
+
+
+
+
+
+
+ The Project menu
+
+
+
+
+
+
+ The Project menu
+
+
+
+ Add Circuit...
+
+
+
+ Adds a new circuit into the current project. Logisim will insist that you name the new circuit. The name must not match any existing circuits in the project.
+
+
+
+ Add VHDL Entity...
+
+
+
+ --
+
+
+
+ Import VHDL Entity...
+
+
+
+ --
+
+
+
+ Load Library
+
+
+
+ Loads a library into the project. You can load three types of libraries, as explained elsewhere in the User's Guide.
+
+
+
+ Unload Libraries...
+
+
+
+ Unloads current libraries from the project. Logisim will not permit you to unload any libraries currently being used, including libraries containing components appearing in any project circuits, as well as those with tools that appear in the toolbar or that are mapped to the mouse.
+
+
+
+ Move Circuit Up
+
+
+
+ Moves the currently displayed circuit one step up the list of circuits within the project, as displayed in the explorer pane.
+
+
+
+ Move Circuit Down
+
+
+
+ Moves the currently displayed circuit one step down the list of circuits within the project, as displayed in the explorer pane.
+
+
+
+ Set As Main Circuit
+
+
+
+ Sets the currently displayed circuit to be the project's main circuit. This menu item will be grayed out if the current circuit is already the project's main circuit. The only significance of the main circuit is that it is the circuit that first appears when a project file is opened.
+
+
+
+ Remove Circuit
+
+
+
+ Removes the currently displayed circuit from the project. Logisim will prevent you from removing circuits that are used as subcircuits, and it will prevent you from removing the final circuit in a project.
+
+
+
+ Revert To Default Appearance
+
+
+
+ If you've edited the circuit's appearance, this menu item reverts the appearance back to the default. The menu item is enabled only when editing the circuit's appearance. The appearance of the default appearance can be changed by the Use new box layout property of the library.
+
+
+
+
+
+ Edit Circuit Layout
+
+
+
+ Switches to allow you to edit the layout of components, which determines how the circuit works. This menu item is usually disabled since you will usually be editing the layout anyway.
+
+
+
+ Edit Circuit Appearance
+
+
+
+ Switches to allow you to edit how the circuit will be represented when it is used as a subcircuit within another circuit. But this menu option allows you to draw a different appearance for the subcircuit.
+
+
+
+ Analyze Circuit
+
+
+
+ Note: This menu is disabled by default in the current version of logisim-evolution. It can be reactivated by command line options.
+
+ Computes a truth table and Boolean expressions corresponding to the current circuit, displaying them in the Combinational Analysis window. The analysis process will only be valid for combinational circuits. A full description of the analysis process is described in the Combinational Analysis section.
+
+
+
+ Get Circuit Statistics
+
+
+
+ Shows a dialog containing statistics about components used by the currently viewed circuit. The dialog includes a table with five columns:
+
+
+
+
+
+
Component: The name of the component.
+
+
Library: The name of the library from which the component came.
+
+
Simple: The number of times that component appears directly within the viewed circuit.
+
+
Unique: The number of times that component appears in the circuit's hierarchy, where each subcircuit within the hierarchy is counted only once.
+
+
Recursive: The number of times that component appears in the circuit's hierarchy, where we count each subcircuit as many times as it appears in the hierarchy.
+
+
+
+ The distinction between "Unique" and "Recursive" is easiest to explain by considering the 4:1 multiplexer built using three 2:1 multiplexers as in the Using subcircuits section. The 2:1 multiplexer contains two AND gates (and the 4:1 circuit includes none), so the "Unique" count of AND gates would be 2; but if you were to build the 4:1 multiplexer using this diagram, you would actually need 2 AND gates for each of the three 2:1 multiplexers, so the "Recursive" count is 6.
+
+
+ If you are using circuits from a loaded Logisim library, those components are considered to be black boxes: The contents of the library's circuits are not included in the unique and recursive counts.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/menu/simulate.html b/src/main/resources/doc/en/html/guide/menu/simulate.html
new file mode 100644
index 0000000000..a07b67d01d
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/menu/simulate.html
@@ -0,0 +1,150 @@
+
+
+
+
+
+
+
+
+
+ The Simulate menu
+
+
+
+
+
+
+ The Simulate menu
+
+
+
+ Simulation EnabledCtrl-E
+
+
+
+ If checked, circuits viewed will be "live:" That is, the values propagating through the circuit will be updated with each poke or change to the circuit.
+
+
+ The menu option will be automatically unchecked if circuit oscillation is detected.
+
+
+
+ Step SimulationCtrl-I
+
+
+
+ Advances the simulation one step forward. For example, a signal may end up entering a gate during one step, but the gate won't show a different signal until the next simulation step. To help identify which points in the overall circuit have changed, any points whose values change are indicated with a blue circle; if a subcircuit contains any points that have changed in it (or its subcircuits, recursively), then it will be drawn with a blue outline.
+
+
+
+ Reset SimulationCtrl-R
+
+
+
+ Clears everything about the current circuit's state, so that it is as if you have just opened the file again. If you are viewing a subcircuit's state, the entire hierarchy is cleared.
+
+
+
+
+ VHDL Simulation Enabled
+
+
+
+ not documented yet
+
+
+
+ Restart VHDL simulatior
+
+
+
+ not documented yet
+
+
+
+ Go Out To State
+
+
+
+ When you delve into a subcircuit's state via its pop-up menu, the | Go Out To State | submenu lists the circuits above the currently viewed circuit's state. Selecting one displays the corresponding circuit.
+
+
+
+ Go In To State
+
+
+
+ If you have delved into a subcircuit's state and then moved back out, this submenu | Go In To State | lists the subcircuits below the current circuit. Selecting one of the circuits displays the corresponding circuit.
+
+
+
+ Tick half cycleCtrl-T
+
+
+
+ Advances the clocks in the simulation by one tick when using the step-by-step mode. A clock set with a high/low duration of 1 tick will then advance by half a cycle.
+ This can be useful when you want to advance the clocks manually, especially when the clock is not in the same circuit as the one you are currently viewing.
+
+
+
+ Tick full cycleF2
+
+
+
+ Same function as before, but advances by two ticks. A clock set with a high/low duration of 1 tick will then advance one complete cycle. The other clocks of the project advance simultaneously in proportion to their parameters.
+
+
+
+ Ticks EnabledCtrl-K
+
+
+
+ Starts automatically ticking the clock. This will have an effect only if the circuit contains any clock devices (in the Wiring library). The option is disabled by default.
+
+
+
+ Tick Frequency
+
+
+
+ Allows you to select how often ticks occur. For example, 8 Hz means that ticks will occur eight times a second. A tick is the base unit of measurement for the speed of clocks.
+
+ Note: that the clock cycle speed will be slower than the tick speed: The fastest possible clock will have a one-tick up cycle and a one-tick down cycle; such a clock would have up/down cycle rate of 4 Hz if the ticks occur at 8 Hz.
+
+
+
+ Logging...
+
+
+
+ Enters the logging module, which facilitates automatically noting and saving values in a circuit as a simulation progresses.
+
+
+
+
+ Vector of tests
+
+
+ The window Vector of tests Allows you to check your circuits thanks to a test vector file that presents the inputs and outputs of the circuit.
+
+ Logisim supports two categories of configuration options: application preferences and project options. The application preferences address preferences that span all open projects, whereas project options are specific to that one project. This section discusses project options; application preferences are described in another section.
+
+
+ You can view and edit project options via | Project |→| Options... |. It brings up the Options window with several tabs.
+
+
+
+
+
+ We will discuss each of these tabs separately.
+
+ By default, when you click the mouse in Logisim's drawing area, the currently selected tool will be used. If you right-click or control-click, it will display a pop-up menu for the current component below the mouse.
+
+
+ Logisim allows you to modify this behavior, relieving you of the need to go to the toolbar and/or the explorer all the time. (This may also be handy if you are left-handed.) Each combination of a mouse button and a modifier key (any subset of shift, control, and alt) can be mapped to a different tool. The Mouse tab allows you to configure these mappings.
+
+
+
+
+
+
+
+ On the left side is an explorer where you can choose the tool you want to map.
+
+
+
+
+ On the right top side is a rectangle in which you can click using the mouse combination you want to click. For example, if you want to create new wires by shift-dragging, then you would first select the Wiring Tool in the Explorer (under the Base library); and then you would shift-click where it says "Click Using Combination To Map Wiring Tool." If that combination is already being used, then the mapping would be replaced with the new tool.
+
+
+
+
+ Below this area is a list of current mappings. Note that any combinations that aren't listed simply use the currently selected tool.
+
+
+
+
+ Below is the Remove button, where you can delete the mapping that is currently selected in the table above the button. In the future, then, that mouse combination would map to whatever tool is currently selected in the toolbar or the explorer pane.
+
+
+
+
+ Below this is a list of attributes for the tool currently selected in the list of mappings. Each mouse-mapped tool has its own set of attributes, different from the attributes used in the explorer pane and in the toolbar. You can edit those attribute values here.
+
+
+
+
+ The Reset Tab
+
+
+
+
+
+ This tab is very simple. Using only the Reset to Model button will reset All Settngs to the model setting set in the The Template tab.
+
+ The Simulation tab allows configuration of the algorithm used for simulating circuits. These parameters apply to all circuits being simulated in the same window, even for circuits that exist in other libraries loaded within the project.
+
+
+
+
+
+
+
+ The The memories are initialized in a random state check box allows to determine how RAMs, registers (D, T, J-K) and counters are initialized. If the box is unchecked, all components will be initialized with a 0.
+ In the other case, when you open the project, drop a component or reset the simulation; register-type components will be initialized with an undefined value and RAMs will be initialized with a random series.
+
+
+
+
+ The Iterations Until Oscillation drop-down menu specifies how long to simulate a circuit before deciding that it is oscillating. The number represents the number of clicks of the internal hidden clock (a simple gate takes just one click). The default of 1,000 is good enough for almost all purposes, even for large circuits.
+ But you may want to increase the number of iterations if you are working with a circuit where Logisim reports false oscillations. This is unlikely to be a problem in practice, but one such a circumstance is a circuit that incorporates many of the below latch circuits with random noise enabled. You may want to decrease the number of iterations if you are working with a circuit that is prone to oscillating and you are using an unusually slow processor.
+
+
+
+
+ The Gate Output When Undefined drop-down menu configures how the built-in logic gates behave when some inputs are unconnected or are floating. By default, Logisim ignores such inputs, allowing a gate to work over fewer inputs than it was designed for. However, in real life, a gate will behave unpredictably in such a situation, and so this drop-down menu allows one to change the gates so that they treat such disconnected inputs as errors.
+
+
+
+
+ The Add Noise To Component Delays checkbox allows you to enable or disable the random noise that is added to the delays of components. The internal simulation uses a hidden clock for its simulation, and to provide a somewhat realistic simulation, each component (excluding wires and splitters) has a delay between when it receives an input and when it emits an output. If this option is enabled, Logisim will occassionally (about once every 16 component reactions) make a component take one click longer than normal.
+
+
+ I recommend keeping this option off, as this technique does introduce rare errors with normal circuits.
+
+ The Toolbar tab allows you to configure what tools appear in the toolbar.
+
+
+
+
+
+ The left side is an explorer listing all the tools available, and the list on the right side displays the current contents of the toolbar. (Three dashes "---" indicate a separator, which is drawn as a gray line.) Between the explorer and the list are five buttons and a combo box:
+
+
+
+
+ Add Tool adds the currently selected tool in the explorer at left to the end of the toolbar.
+
+
+
+
+ Add Separator adds a separator to the end of the toolbar.
+
+
+
+
+ Move Up moves the currently selected item of the toolbar up/left one spot.
+
+
+
+
+ Move Down moves the currently selected item of the toolbar down/right one spot.
+
+
+
+
+ Remove removes the currently selected item from the toolbar.
+
+
+
+
+ The attributes associated with the tools are not displayed in this window; instead, you can view and edit them within the main drawing window.
+
+ Logisim supports two categories of configuration options: application preferences and project options. The application preferences address preferences that span all open projects, whereas project options are specific to that one project. This section discusses application preferences; project options are described in another section.
+
+
+ You can view and edit application preferences via the menu | File |→| Preferences... | (or, under Mac OS, the Logisim menu), a window will appear with several tabs. We will discuss these tabs separately, and then we will see how preferences can be configured from the command line.
+
+ You can configure many of Logisim's application preferences via command line options. This can be particularly useful in a laboratory of single-student computers where you want Logisim to start up the same for students every time, regardless of how previous students may have configured the program.
+
+
+ The overall command-line syntax is as follows.
+
+
+
java -jar jarFileName[options][filenames]
+
+
+
+ The optional additional files named on the command line will be opened as separate windows within Logisim.
+
+
+ The following example starts Logisim in its basic configuration.
+
+
+
java -jar jarFileName -plain -gates shaped -locale en
+
+
+
+ Supported options include the following.
+
+
+
+ -plain
+
+
+ -empty
+
+
+ -template templateFile
+
+
+
+ Configures the template for Logisim to use.
+
+
+
+ -gates [shaped|rectangular]
+
+
+
+ Configures which type of gate to use.
+
+
+
+ -locale localeIdentifier
+
+
+
+ Configures which translation to use. As of this writing, the supported locales include:
+
+
+
+
+
+ de German
+
+
+
+
+ el Greek
+
+
+
+
+ en English
+
+
+
+
+ es Spanish
+
+
+
+
+ fr French
+
+
+
+
+ pt Portugais
+
+
+
+
+ ru Russian
+
+
+
+
+ it Italian
+
+
+
+
+ nl Dutch
+
+
+
+
+
+
+ -accents [yes|no]
+
+
+
+ This is only relevant for languages that use characters outside the 7-bit ASCII character set; this would include languages using accented characters, and it would not include English. If no, characters outside the 7-bit ASCII character set are replaced with equivalents appropriate to the language; this would be useful for Java/OS combinations where such characters are not supported well.
+
+
+
+ -clearprops
+
+
+
+ Clear all application preferences at startup, so Logisim will act as if it were being executed on the host system for the first time.
+
+
+
+ -nosplash
+
+
+
+ Hides the initial Logisim splash screen.
+
+
+
+ -help
+
+
+
+ Displays a summary of the command line options.
+
+
+
+ -version
+
+
+
+ Displays the Logisim version number.
+
+
+
+ -noupdates
+
+
+
+ Do not update the software.
+
+
+
+ -analyze
+
+
+
+ Displays the combinatorial analysis menus.
+
+
+
+ -load filename
+
+
+
+ Load an image in RAM (works only with -tty)
+
+
+
+ -sub file1file2
+
+
+
+ load the file by replacing the library file (file1) with the library file (file2). More information in Substituting libraries
+
+ Run the circuitname tests in projectfile based on vectors in vectorfile. More information in Window Text Vector
+
+
+
+ -geom WxH|WxH+X+Y
+
+
+
+ Opens Logisim with a window dimensioned according to the parameters W (width) and H (height) or with the upper left corner positioned according to the parameters X,Y.
+ Example: -geom 600x400+100+100
+
+ These preferences enable features that are considered experimental, inserted to garner user feedback.
+
+
+
+ Graphics acceleration: One Logisim user observed that adding -Dsun.java2d.d3d=True to the command line seemed to improve Logisim's graphics performance by telling it to use hardware graphics acceleration. This drop-down box attempts to configure Logisim to set this up; reports about whether this drop-down box has any effect on performance would be welcome. It won't have any effect until Logisim is restarted.
+
+
+
diff --git a/src/main/resources/doc/en/html/guide/prefs/pref-intl.html b/src/main/resources/doc/en/html/guide/prefs/pref-intl.html
new file mode 100644
index 0000000000..c4cfa53ff0
--- /dev/null
+++ b/src/main/resources/doc/en/html/guide/prefs/pref-intl.html
@@ -0,0 +1,107 @@
+
+
+
+
+
+
+
+
+
+ The International tab
+
+
+
+
+
+
+ The International tab
+
+
+
+
+
+ This tab allows configuration of Logisim according to regional preferences.
+
+
+
+
+ Gate shape: Logisim supports two standards for drawing gates: IEC and ANSI. The following table illustrates the distinction.
+
+
+
+
+
+
+
+ IEC
+
+
+ ANSI
+
+
+
+
+
+ AND
+
+
+
+
+
+
+
+ OR
+
+
+
+
+
+
+ Because the IEC style tends to be more popular in the U.S., while the ANSI<(i>) style tends to be more popular in Europe, some people refer to these styles according to these regions.
+
+
+ Logisim does not follow any standard exactly; it steers a middle ground to allow switching between them. In particular, the shaped gates are more square than the dimensions defined by the relevant IEEE standard. And, although XOR and XNOR gates really ought to be the same width as OR and NOR gates with the ANSI style, they are not because of difficulties compressing the IEC XOR gate.
+
+
+
+
+ Language: Change between languages. The current version is supplied with English, Spanish, Russian, and German translations.
+
+
+
The French translation was introduced partially with Logisim 2.13.22. Produced by Roberto Rigamonti and completed in Logisim 2.14.2 by Marc-André Baillifard Université de Lausanne
+
+
The German translation was introduced with Logisim 2.6.1. It is by Uwe Zimmermann, a faculty member at Uppsala University in Sweden.
+
+
The Greek translation was introduced with Logisim 2.7.0. It is by Thanos Kakarountas, a faculty member at Technological Educational Institute of Ionian Islands in Greece.
+
+
The Italian translation was introduced with Logisim 2.14.7
+
+
The Nederlands translation was introduced with Logisim 3.2.0
+
+
The Portuguese translation was introduced with Logisim 2.6.2. It is by Theldo Cruz Franqueira, a faculty member at Pontifícia Universidade Católica de Minas Gerais in Brazil.
+
+
The Russian translation was introduced with Logisim 2.4.0. It is by Ilia Lilov, from Russia.
+
+
The Spanish translation was complete as of Logisim 2.1.0, but subsequent Logisim versions have added new options that remain untranslated. It was contributed by Pablo Leal Ramos, from Spain.
+
+
+
+ Due to the changes, not all translations are at the same level and there is still a lot to be translated and corrected. Logisim translations and documentation are welcome! If you are interested, please contact github.com/reds-heig/logisim-evolution. This will not be a commitment: I will be happy to hear of your interest, and I will tell you whether I know of somebody who is working on it already, prepare a version for you to work with, and send you instructions. The translation process does not require an understanding of Java.
+
+
+
+
+ Replace accented characters: Some platforms have poor support for characters (such as ñ or ö) that do not appear in the 7-bit ASCII character set. When this is checked, Logisim will replace all instances of the characters with the appropriate equivalent 7-bit ASCII characters. The checkbox is disabled when the current language does not have any equivalents available (as with English).
+
+ This tab includes preferences affecting the behavior of the circuit layout editor.
+
+
+
+
Use anti-aliasing: Activates the anti-aliasing effect of the graphics card. Tracks will appear smoother on the screen or print.
+
+
+
+
+ Printer view: Specifies whether to display the circuit on the screen in the same way it is displayed through the printer. Normally this is off, and Logisim displays the on-screen circuit with indications of the current circuit state, and it displays some hints about component interface (most notably, it draws legs on OR gates to indicate where they would connect). The printer view, though, omits indications of state, and it omits such interface hints.
+
+
+
+
+
+
+ Uses a colorblind color scheme Thread colours will be changed to accommodate people with colour perception difficulties.
+
+
+
+ Show attribute halo: Specifies whether to draw the pale teal oval around the component or tool whose attributes are currently displayed in the attribute table.
+
+
+
+
+
+
+ Uses animated icons
+
+
+
+ Show component tips: Specifies whether to display the "tool tips" that will temporarily appear when the mouse hovers over components supporting them. For example, if you hover over a subcircuit component's pin, it will display the label of the corresponding pin within the subcircuit. Hovering over one of the ends of a splitter will tell you the bits to which that end corresponds. In addition, all components in the Plexers, Arithmetic, and Memory libraries will provide information about their inputs and outputs via tips.
+
+
+
+
+ Keep connections while moving: Indicates whether Logisim should add new wires when components are moved to preserve their connections. By default this is on — though it can be turned off temporarily by pressing the shift key while moving the components. If this box is unchecked, then the default will be not to add wires during a move — though you can turn it on temporarily by pressing the shift key during the move.
+
+
+
+
+ Show Ghosts while adding: When checked, and when a tool for adding a new component is selected, a light-gray outline of a component to be added is drawn as the mouse moves across the canvas. For example, if you select the AND gate tool and move the mouse into the window (without pressing the mouse's button), a gray outline of an AND gate will display where the AND gate will appear when the mouse is clicked.
+
+
+
+ Use fixed size circuit boxes: The default appearance of the sub-circuits in new logisim-evolution projects will be proposed with a standard size and if not adapted according to the circuit. It is also possible to do this on a case-by-case basis with the property of the sub-circuits. Use fixed boxe size
+
+
+ Use the new input and output symbol: The new input and output symbols will be used, if not the old ones.
+ input and output symbols will be used, if not the old ones . Pop-up window will ask you if you need to convert them into the current circuit diagram.
+
+
+ Use the default appearance provided by: The appearance of certain circuits, for example memories, will be proposed according to the versions of logisism :Logisim- Classique, Logisim-HolyCross ,Logisim-Evolution
+
+
+
+ After adding component: By default, after adding each individual component, Logisim switches back to the Edit Tool to allow you to move components around and to add wires. The drop-down box allows you to change this behavior so that Logisim stays at the same tool for adding more of the same component, until you yourself opt to choose the Edit Tool. (This was Logisim's default behavior prior to Logisim 2.3.0. While more intuitive, this behavior requires more mouse movement to switch between tools.)
+
+
+
+
+ First radix when wire poked: Configures how values are displayed when a wire is clicked using the Poke Tool. Clicking a wire displays temporarily the value, staying until the user clicks elsewhere in the circuit.
+
+
+
+
+
+
+
+ Second radix when wire poked: Configures the second part of how wire values are displayed.
+
+ A template is a Logisim file that is used as a starting point whenever Logisim creates a new project. Also, if you have an existing Logisim file with a strangely configured environment, you can "reset" the environment using the Reset All Settings button in the window for editing Project options| Project |→| Options ... |→| Reset |.
+
+
+ Although templates are useful in other situations also, they are particularly suited for classroom use, where an instructor might want to distribute a template for students to start from. This is particularly likely if the class uses Logisim heavily, including many of the more advanced features, in which case the simple default configuration may prove too simple. Templates can also be useful in the classroom setting when the instructor opens a file submitted by a student who has configured the environment significantly.
+
+
+ By default, the Plain template option will be selected, using the default template shipped with Logisim. If you want a bare-bones configuration, you might choose Empty template. But if you want to designate another file to use as the template, select a template via the Select... button, and then choose the Custom template option.
+
+
+ It is also possible to select a template by a command line parameter: -templatetemplateFile
+
+ This tab includes preferences affecting the appearance of the main window used for Logisim.
+
+
+
+
+ Show tick rate: If checked, then when ticks are enabled, Logisim displays a measurement of the rate at which it has been able to complete ticks. The tick rate is measured by averaging over the previous 1,000 ticks. (Disabling ticks or changing the maximum tick rate will clear its history.)
+
+
+ This actual tick rate may be much less than the selected tick rate, because Logisim cannot simulate larger circuits at a very fast rate. For example, Logisim's maximum speed for a reasonably large circuit might be 16 Hz; you can select a faster tick rate, but the actual speed will not exceed 16 Hz.
+
+
+
+
+ Toolbar location: This drop-down menu configures the location of the toolbar within the overall window. The toolbar may be placed on any of the window's four borders, described as north, south, east, and west. It may also be hidden, or it can be placed "down the middle" - that is, to the left of the canvas but to the right of the explorer pane and attribute table.
+
+
+
+
+ Zoom factor: Allows you to set a zoom factor on the entire interface. This for use on HD screens. Instead, recommend using the OS's capabilities for this.
+ Requires to restart the program.
+
+
+
+
+ Look and feel: Allows you to select a number of look of the interface to experiment according to your tastes.
+ Requires to restart the program.
+
+ As an example of the level of sophistication of Logisim's algorithm, consider the following circuit.
+
+
+
+
+
+ This "obviously" always outputs 0. But NOT gates don't react instantaneously to their inputs in reality, and neither do they in Logisim. As a result, when this circuit's input changes from 0 to 1, the AND gate will briefly see two 1 inputs, and it will emit a 1 briefly. You won't see it on the screen. But the effect is observable when we use the AND gate's output as an input into the clock of a D flip-flop.
+
+
+
+
+
+ Poking the 0 input to become 1 leads to an instantaneous 1 going into the D flip-flop, and thus the flip-flop's value will toggle every time the circuit input goes from 0 to 1. The detailed sequence can also be observed thanks to the step-by-step mode of the simulation.
+
+
+ Every component has a delay associated with it. More sophisticated components built into Logisim tend to have larger delays, but these delays are somewhat arbitrary and may not reflect reality.
+
+
+
+ Logisim world
+
+ Real world
+
+
+ From a technical point of view, it is relatively easy to deal with this level of sophistication in a single circuit. Dealing with gate delays well across subcircuits, though, is a bit more complex; Logisim does attempt to address this correctly by placing all primitive component's propagation values into a single schedule regardless of the subcircuit in which the component lies.
+
+
+ Via the Project Options window's Simulation tab, you can configure Logisim to add a random, occasional delay to a component's propagation. This is intended to simulate the unevenness of real circuits. In particular, an R-S latch built using two NOR gates will oscillate without this randomness, as both gates will process their inputs in lockstep. This randomness is disabled by default.
+
+
+ Note that I'm stopping short of saying that Logisim always addresses gate delays well. But at least it tries.
+
+ Logisim's algorithm for simulating the propagation of values through circuits is not something that you normally need to worry about. Suffice it to say that the algorithm is sophisticated enough to account for gate delays, but not realistic enough to account for more difficult phenomena like varying voltages or race conditions.
+
+ The propagation algorithm, which normally works silently without any problems, will become very visible when you create a circuit that oscillates.
+
+
+
+
+
+ This circuit is currently in a stable condition. But if you change the input to 1, the circuit will effectively enter an infinite loop. After a while, Logisim will simply give up and show an "Oscillation apparent" message telling you that it believes that the circuit is oscillating.
+
+
+
+
+
+ It will display the values it has at the time it gives up. These values will look wrong - in this screen shot, the AND gate is emitting 1 although one of its inputs is 0, but it could be that the NOT gate has a 1 input and a 1 output.
+
+
+ Logisim helpfully circles in red each location that seems to be involved in the oscillation. If an involved point lies within a subcircuit, Logisim will draw that subcircuit's outline in red.
+
+
+ When Logisim detects oscillation, it shuts down all further simulation. You can re-enable simulation using the menu | Simulate |→| Simulation Enabled |.
+
+
+ Logisim detects oscillation using a fairly simple technique: If the circuit simulation seems to many iterations, then it will simply give up and report oscillation. (The points it identifies as being involved are those that were touched in the last 25% of the iterations.) Thus, it could erroneously report oscillation, particularly if you are working with an exceptionally large circuit; but it would be one that is larger than any I have built using Logisim. In any case, if you are confident that the reporting is in error, you can configure the number of iterations completed before oscillation occurs via the Project Options window's Simulation tab.
+
+ Logisim's propagation algorithm is more than sophisticated enough for almost all educational purposes; but it is not sophisticated enough for industrial circuit design. In order from most damning to least damning, the shortcomings of Logisim's propagation technique include:
+
+
+
+
+ Except for the issue of gate delays, Logisim does not particularly concern itself with timing issues. It is very idealized, so that a pair of NOR gates in an S-R latch configuration will toggle in lockstep infinitely, rather than the circuit eventually settle into a stable state.
+
+
+
+
+ Logisim cannot simulate subcircuits whose pins sometimes behave as inputs and sometimes behave as outputs. Components built using Java can have such pins, though: Within the built-in libraries, the Memory library's RAM circuit contains a D pin that can act both as an input and as an output.
+
+
+
+
+ Logisim cuts off its simulation after a fixed number of iterations assuming that there is an oscillation error. Conceivably, a large circuit that does not oscillate could lead to trouble.
+
+
+
+
+ Logisim does nothing with respect to discriminating between voltage levels: A bit can be only on, off, unspecified, or error.
+
+
+
+
+ There are additional shortcomings, too, that I have omitted because they are so obscure that if you were aware of them, it would be obvious that Logisim comes nowhere close to that level. As an extreme example, I have a friend who works for a major chip manufacturer, and his job is to worry about "bubbles" in chips' nanometer-wide wires growing and leading to random disconnection.
+
+
+
+
+ Even beyond this, I am not a circuit design specialist; thus, there may well be errors in the propagation technique of which I am not aware. I welcome corrections from experts.
+
The dynamic components provides the means of observing/manipulating
+ components that are hidden in a sub-circuit on a higher level. Example:
+ You have placed a led in a circuit named MyNiceCircuit.
+ Now you use MyNiceCircuit as sub-circuit in the circuit
+ named MyToplevel. Simulating in MyToplevel
+ will hide your led, hence you have no means to see if the led in MyNiceCircuit
+ is lighting up or not. The dynamic components help here by providing the
+ possibility of putting an image of the led on the sub-circuit symbol of MyNiceCircuit.
+ To add dynamic components to the sub-circuit symbol of MyNiceCircuit,
+ you have first to open the appearance editor
+ of the circuit MyNiceCircuit. Than you click on the -tool
+ icon. A window will open listing all the available dynamic components, and
+ you can select which one to show in the appearance of your sub-circuit
+ symbol. Note that the dynamic components feature is a recursive property.
+ This means that if you have a hierarchical structure, it will show all
+ possible dynamic components available down from the current sub-circuit.
+
Currently following tools support dynamic components:
+ As you build circuits that are more and more sophisticated, you will want to build smaller circuits that you can use multiple times as a module nested within larger circuits. In Logisim, such a smaller circuit that is used in a larger circuit is called a subcircuit.
+
+
+ If you're familiar with computer programming, you're familiar with the subprogram concept, whether it's called a subroutine, function, method, or procedure in your favored language. The subcircuit concept is analogous to this, and it serves the same purpose: To break a large job into bite-sized pieces, to save the effort of defining the same concept multiple times, and to facilitate debugging.
+
+ There are four models of graphical representation for the cicuit (Logisim-Classical,Logisim-holycross,Logisim-Evolution and Personalized). The version of the presentation is selectable in the Circuit Appearance property.
+
+
+ In the Logisim-Evolution appearance, the sub-circuit is drawn in a rectangle with the name of the circuit to the south in a black rectangle. The dimension of the circuit drawing is adapted to the content if the Fixed box size property is no. The inputs will be positioned to the east and the outputs to the west according to the order of their appearance (from left to right and from top to bottom) in the detailed drawing. The anchor is at the top of the northwestern pine.
+
+
+
+
+
+ In the Logisim-holycross appearance the sub-circuit is drawn in a rectangle with the name of the circuit to the north, the inputs to the east and the outputs to the west. The inputs will be positioned to the east and the outputs to the west in the same way as in the previous appearance.
+
+
+
+
+
+ In the Logisim-Classical appearance the sub-circuit is drawn in an unnamed rectangle, its size will depend on the number of inputs and outputs. The input and output will be positioned on the north, south, east, west sides according to their orientation and the order of their appearance (from left to right and from top to bottom) in the detailed diagram. The anchor is at the top of the northwestern pine.
+
+
+
+
+
+ It is possible to edit a label on the subcircuit instance by double-clicking on the rectangle. The position of the font and the attributes of the font can be modified in the property table. The same table allows the setting of the another shared label (for all instances).
+
+
+
+ Every Logisim project is actually a library of circuits. In its simplest form, each project has only one circuit (called main by default), but it is easy to add more: Click on the of the small menu bar above the navigation panel or right click on the root of the tree in the navigation panel or else select | Project |→| Add Circuit... | and then type any name you like for the new circuit you want to create.
+
+ Note: The name of the circuits must begin with a letter (A..Z, a..z) it can contain the signs (., _) And numbers.
+
+
+ Suppose we want to build a 2-to-1 multiplexer named Mux_2to1." After adding the circuit, Logisim will look like this.
+
+
+
+
+
+ In the explorer pane, you can now see that the project now contains two circuits, main, and Mux_2to1 Logisim draws a magnifying glass over the icon of the circuit currently being viewed; the current circuit name also appears in the window's title bar.
+
+
+ After editing the circuit to appear like a Mux_2to1, we might end up with the following circuit.
+
+ As you test larger circuits, you will likely find bugs. To nail down what's going wrong, exploring what's going on in the subcircuits while running the overall circuit can help. To enter the subcircuit's state, you can use any of three different techniques.
+
+
+ The most straightforward is probably to view the simulation hierarchy by by clicking on the Simulate tab, or by selecting menu | Project |→| View Simulation Tree |. This switches the explorer pane so that it shows the hierarchy of subcircuits being simulated.
+
+
+
+
+
+ Double-clicking an element in this hierarchy will display what is happening inside that subcircuit.
+
+
+ The second way you can enter a subcircuit is to bring up its popup menu by right-clic or Ctrl+Click it, and then choosing the option | View "circuit_name" |.
+
+
+
+
+
+ And the third way is to first ensure the Poke Tool () is selected and then click the subcircuit you want to enter; a magnifying glass will appear over the subcircuit's center, and double-clicking the magnifying glass will enter the subcircuit's state.
+
+
+
+
+
+ In any case, once you enter the subcircuit, you'll see that the pins' values in the subcircuit match the values being sent through them from the containing circuit.
+
+
+
+
+
+ While in the subcircuit, you are allowed to alter the circuit. If the changes affect any of the subcircuit's outputs, they are propagated into the containing circuit. One exception: The subcircuit inputs are determined based on the values coming into the circuit from the supercircuit, so it doesn't make sense to toggle those values. If you attempt to poke a subcircuit's input, a dialog will pop up asking, The pin is tied to the supercircuit state. Create a new circuit state? Clicking No will cancel the toggle request, while clicking Yes will create a copy of the viewed state, divorced from the outer circuit, with the input pin toggled.
+
+
+ Once you have completed viewing and/or editing, you can return to the parent circuit either by double-clicking the parent circuit in the explorer pane, or via the menu | Simulate |→ | Go Out To State "circuit_name" |.
+
+ Every Logisim project is automatically a library that can be loaded into other Logisim projects: Just save it into a file and then load the library within another project with the menu | Projet |→| Load Library |→| logisim-evolution library... |. All of the circuits defined in the first project will then be available as subcircuits for the second. This feature allows you to reuse common components across projects and to share favorite components with your friends (or students).
+ Below our project loaded as a library is available in the navigation panel.
+
+
+
+
+
+ Note: The library must not contain a circuit with the same name as a circuit already present in the project.
+
+
+ Each project has a designated main circuit, which can be changed to refer to the current circuit via the menu | Project |→| Set As Main Circuit |. The only significance of this is that the main circuit is the one that is displayed when you first open the project. The default name ("main") of the circuit in a newly created file has no significance at all, and you can feel free to delete or rename that circuit.
+
+
+ With a loaded Logisim library, you are allowed to view circuits and manipulate their states, but Logisim will prevent you from altering the circuits' design and other data stored within the file.
+
+
+ If you want to alter a circuit in a loaded Logisim library, then you need to open it separately within Logisim. As soon as you save it, the other project should automatically load the modified version immediately; but if it does not, you can right-click the library folder in the explorer pane and select | Reload Library |.
+
+ The default appearance is very usable, and indeed Logisim existed for many years with no other option. If, however, you prefer that the subcircuit be drawn differently, you can select | Project |→| Edit Circuit Appearance | , and
+ Logisim's interface will switch from its regular layout-editing interface to an interface for drawing the circuit's appearance. You can also click the far-right icon () in the explorer pane's upper toolbar. Below, we are editing the 2:1 multiplexer's appearance so that it is drawn with the usual trapezoid rather than a rectangle.
+
+
+
+
+
+ With the appearance for the 2:1 multiplexer drawn as above, the layout for the 4:1 multiplexer would then appear as the following.
+
+
+
+
+
+ The appearance editor is like a traditional drawing program, but there are a few special symbols for indicating how the drawing works when placed into a circuit's layout. These special symbols cannot be removed.
+
+
+
+
+ The green circle with a line coming out of it, which we'll call the anchor. () There is exactly one anchor in each subcircuit appearance. Each component in a circuit has a single point identifying its
+ location; a user sees this when creating a new component: The mouse click identifies just a single location, and the component is placed relative to that (usually with the primary output at the mouse's location) The anchor identifies the mouse's location relative to the overall drawing
+ when the subcircuit is created.
+
+
+ The anchor also identifies the appearance's facing, as indicated by the direction the anchor's line points from its circle. When placing the subcircuit into a layout, the user can change the subcircuit's facing; the anchor's facing indicates in which direction the appearance is
+ oriented. In our example, the anchor is facing east, and each instance of the subcircuit in the Mux_4to1 is also facing east, so they are all drawn in the same orientation as the Mux_2to1 appearance.
+
+
+
+
+ The blue circles () and squares with dots () in them are the subcircuit's ports. There are exactly as many ports as there are
+ input and output pins in the circuit. Ports corresponding to inputs are drawn as squares, while ports corresponding to outputs are drawn as circles. Each port indicates how a wire connecting into the circuit will correspond to an input or output pin within the layout.
+
+
+
+
+ When you select a port, Logisim will indicate the corresponding pin by popping up a miniature diagram of the layout in the window's bottom right corner, with the corresponding pin(s) drawn in blue. This does not happen when all ports are selected.
+
+
+
+
+
+ We can change the zoom of the image with a Ctrl+Mouse Wheel or by using the magnifying glass buttons or the slider at the bottom left of the workspace. The rate is displayed.
+
+
+ The toolbar contains tools for adding additional shapes, as shown below. Some keys (Ctrl,Alt,Shift) have an effect on the way shapes are drawn. These keys can be combined with each other.
+
+
+ Ctrl: Aligns the end points on the grid.
+ Shift: Orient the lines at an angle multiple of 45° or make the figures symmetrical (Square, Rounded Square, Circle).
+ Alt: Draws the figures from their centre.
+
+ Curve tool: Create a quadratic Bezier curve. The first click and drag specifies the beginning of the line, the second click and drag ends the line and sets the curvature. A click on the line shows you
+ the three control points. Schift and click on central control point impose a symmetrical curve. Alt and click on center point draws the curve through the control point (under the mouse).
+
+
+
+
+
+
+
+ Polylines tool Creates a sequence of connected lines, each click starts a new line. A double-click ends the sequence.
+
+
+
+
+
+
+
+ Rectangle tool Create a rectangle or a square with rounded edges ( Shift ) through dragging from one corner to the opposite corner.
+
+
+
+
+
+
+
+ Rectangle tool Create a rectangle or a square ( Shift ) through dragging from one corner to the opposite corner.
+
+
+
+
+
+
+
+ Oval tool Creates an oval or circle ( Shift ) through dragging from one corner of its bounding box to the opposite corner.
+
+
+
+
+
+
+
+ Polygon tool Create an arbitrary polygon, each click starts a new face. A double-click or Enter key or click the starting vertex to complete the shape.
+
+ Now suppose we want to build a 4-to-1 multiplexer using instances of our 2-to-1 multiplexer. Of course, we would first create a new circuit, which we'll call Mux_4to1 To add 2-to-1 multiplexers into our circuit, we click the Mux_2to1 circuit once in the explorer pane to select it as a tool, and then we can add copies of it, represented as boxes, by clicking within the canvas.
+
+
+
+
+
+ If you were to double-click the Mux_2to1 circuit in the explorer pane, then the window would switch to editing the Mux_2to1 circuit instead.
+
+
+ After building up the circuit, we end up with the following.
+
+
+
+
+
+ Our circuit for a 4-to-1 multiplexer uses three copies of the 2-to-1 multiplexer,each is drawn in a box with pins on the left and right sides. The pins on this box correspond to the input and output pins in the Mux_2to1 circuit. The two pins on the east face of the box correspond to the inputs of the circuit and on the west face they correspond to the output. They are read from the diagram of the sub-circuit from right to left and from top to bottom and they will be placed on the sub-circuit symbol from top to bottom.
+
+
+ If labels have been associated with these pins in the diagram they will be included in the symbol. In addition, they are also displayed as a tooltip when you fly over the pin with the mouse. You can disable this feature through the preferences panel .)
+
+
+
+
+
+ Several other components will display these tips, too: For some of the pins of a built-in flip-flop, for example, hovering over it explains what that pin does.
+
+
+ Incidentally, every pin to a circuit must be either an input or an output. Many manufactured chips have pins that behave as an input in some situations and as an output in others; you cannot construct such chips within Logisim (at least, in the current version.
+
+
+ Logisim will maintain different state information for all subcircuits appearing in a circuit. For example, if a circuit contains a flip-flop, and that circuit is used as a subcircuit several times, then each subcircuit's flip-flop will have its own value when simulating the larger circuit.
+
+
+ Now that we have the 4-to-1 multiplexer defined, we can now use it in other circuits. Logisim has no limits on how deeply circuits can be nested - though it will object to nesting circuits within themselves!
+
+
+ Note: There's nothing wrong with editing a circuit that is being used as a subcircuit; in fact, this is quite common. Be aware, though, that any changes to a circuit's pins (adding, deleting, or moving them) will rearrange them also in the containing circuit. Thus, if you change any pins in a circuit, you will also need to edit any circuits using it as a subcircuit.
+
+ Logisim-evolution allows you to design and simulate digital circuits. It is intended as an educational tool, to help you learn how circuits work.
+
+
+ To practice using Logisim, let's build a XOR circuit - that is, a circuit that takes two inputs (which we'll call x and y) and outputs 0 if the inputs are the same and 1 if they are different. The following truth table illustrates.
+
+
+
+
+
+
+ x
+
+
+ y
+
+
+ x XOR y
+
+
+
+
+ 0
+
+
+ 0
+
+
+ 0
+
+
+
+
+ 1
+
+
+ 0
+
+
+ 1
+
+
+
+
+ 0
+
+
+ 1
+
+
+ 1
+
+
+
+
+ 1
+
+
+ 1
+
+
+ 0
+
+
+
+
+
+
+ We might design such a circuit on paper.
+
+
+ But just because it's on paper doesn't mean it's right. To verify our work, we'll draw it in Logisim and test it. As an added bonus, we'll get a circuit that's looks nicer than what you probably would draw by hand.
+
+ Recall that we're trying to build the following circuit in Logisim.
+
+
+
+
+
+
+
+ I suggest building a circuit by inserting the gates first as a sort of skeleton and then connecting them with wires later. The first thing we'll do is to add the two AND gates. Click on the "AND" tool in the toolbar (, the next-to-last tool listed). Then click in the editing area where you want the first AND gate to go. Be sure to leave plenty of room for stuff on the left. Then click the AND tool again and place the second AND gate below it.
+
+
+
+
+
+ Notice the five dots on the left side of the AND gate. These are spots where wires can be attached. It happens that we'll just use two of them for our XOR circuit; but for other circuits, you may find that having more than two wires going to an AND gate is useful. The number of inputs can be modified in the properties "Number of inputs"
+
+
+ Now add the other gates. First click on the "OR" tool (); then click where you want it. And place the two NOT gates into the canvas using the "NOT" tool ().
+
+
+
+
+
+ I left a little space between the NOT gates and the AND gates; if you want to, though, you can put them up against each other and save yourself the effort of connecting them with a wire later.
+
+
+ Now we want to add the two inputs x and y into the diagram. Select the "Input" tool (), and place the pins down. You should also place an output pin next to the OR gate's output using the "Output" tool (). (Again, I'm leaving a bit of space between the OR gate and the output pin, but you might choose to place them right next to each other.)
+
+
+
+
+
+ If you decide you don't like where you placed something, then you can select it using the "Edit" tool () and drag it to the desired spot. Or you can delete it altogether by selecting | Edit | → | Delete | or pressing the Delete key or Ctrl-X keys.
+
+
+ As you place each component of the circuit, you'll notice that as soon as the component is placed, Logisim reverts to the "Edit" tool () so that you can move the recently-placed component or (as we'll see soon) connect the component to others by creating wires. If you want to add a copy of the recently placed component, a shortcut is to press Ctrl-D to duplicate the selection. (Some computers use another keys for menus, such as the Command key on Macintoshes. You would press that key with the D key.)
+
+ When you start Logisim, you'll see a window similar to the following. Some of the details may be slightly different since you're likely using a different system than mine.
+
+ We can quickly dispose of the explorer pane and the attribute table: We won't be examining them in this tutorial, and you can just ignore them. Also, the menu bar is self-explanatory.
+
+
+ That leaves the toolbar and the canvas. The canvas is where you'll draw your circuit; and the toolbar contains the tools that you'll use to accomplish this.
+
+ In certain circumstances of study or in case of subtle problem related to the propagation of the signals, it is very useful to be able to observe these phenomena. Logisim simulates in a slightly naive way the propagation in gates. (the gates all have the same propagation delay), but it still allows to observe the main problems related to these parameters.
+
+
+ For the example, I only give you the key combinations needed for this exercise; you should know that for each key combination there is an equivalent submenu in the menu | Simulation |.
+
+
+
+
+
+ If you build the circuit above you will find that each change from 0 to 1 of the input e disturbs the flip-flop D.
+
+
+ To observe the phenomenon proceed as follows : Bring the circuit to the state where e is 0. Then do Ctrl-E to disable automatic simulation. Push on the input e to switch it to 1. Nothing happens, it's normal. Then use the combination Ctr-I and observe. Do it as many times as necessary.
+
+
+
+
+
+ You will notice blue circles on some ends of thread, these indicate that there is a change in the state of this thread at this step of the simulation. You can observe the brief passage through 1 of the output of the AND gate.
+
+
+ This method also makes it possible to observe asynchronous counter operation or propagation of the carry in an adder.
+
+
+
+
+
+ Now that you are finished with tutorial, you can experiment with Logisim by building your own circuits. If you want to build circuits with more sophisticated features, then you should navigate through the rest of the help system to see what else you can do. Logisim is a powerful program, allowing you to build up and test huge circuits; this step-by-step learning process just scratches the surface.
+
+ Our final step is to test our circuit to ensure that it really does what we intended. Logisim is already simulating the circuit. Let's look again at where we were.
+
+
+
+
+
+ Note that the input pins both contain 0s; and so does the output pin. This already tells us that the circuit already computes a 0 when both inputs are 0.
+
+
+ Now to try another combination of inputs. Select the "Poke" tool () and start poking the inputs by clicking on them. Each time you poke an input, its value will toggle. For example, we might first poke the bottom input (y).
+
+
+
+
+
+ When you change the input value, Logisim will show you what values travel down the wires by drawing them light green to indicate a 1 value or dark green (almost black) to indicate a 0 value. You can also see that the output value has changed to 1.
+
+
+ So far, we have tested the first two rows of our truth table, and the outputs (0 and 1) match the desired outputs.
+
+
+
+
+
+
+ x
+
+
+ y
+
+
+ x XOR y
+
+
+
+
+ 0
+
+
+ 0
+
+
+ 0
+
+
+
+
+ 1
+
+
+ 0
+
+
+ 1
+
+
+
+
+ 0
+
+
+ 1
+
+
+ 1
+
+
+
+
+ 1
+
+
+ 1
+
+
+ 0
+
+
+
+
+
+
+ By poking the switches through different combinations, we can verify the other two rows. If they all match, then we're done: The circuit works!
+
+
+ To archive your completed work, you might want to save or print your circuit. The | File | menu allows this, and of course it also allows you to exit Logisim. But why quit now ?
+
+ Adding text to the circuit isn't necessary to make it work; but if you want to show your circuit to somebody (like a teacher), then some labels help to communicate the purpose of the different pieces of your circuit.
+
+
+ Select the "Text" tool (). You can click on an input pin and start typing to give it a label. (It's better to click directly on the input pin than to click where you want the text to go, because then the label will move with the pin.) You can do the same for the output pin. Or you could just click any old place and start typing to put a label anywhere else.
+
+
+
+
+
+ Many components accept labels, for example if you click in one of the doors you can also assign a label
+
+
+
+
+
+ It is possible to modify a label in several other ways.
+
+
+ With a double click on the component with the "Edit" tool ().
+ With a click on a label with the "Text" tool ().
+ By editing the property "label" in the attribute table.
+
+ After you have all the components blocked out on the canvas, you're ready to start adding wires. Select the "Edit" Tool (). When the scursor is over a point that receives a wire, a small green circle will be drawn around it. Press the left mouse button there and drag as far as you want the wire to go.
+
+
+
+
+
+ Logisim is rather intelligent when adding wires: Whenever a wire ends at another wire, Logisim automatically connects them. You can also "extend" or "shorten" a wire by dragging one of its endpoints using the "Edit" tool ().
+
+
+ Wires in Logisim must be horizontal or vertical. To connect the upper input to the NOT gate and the AND gate, then, I added three different wires.
+
+
+
+
+
+ Logisim automatically connects wires to the gates and to each other. This includes automatically drawing the circle at a T intersection as above, indicating that the wires are connected.
+
+
+ As you draw wires, you may see some blue or gray wires. Blue in Logisim indicates that the value at that point is "unknown," and gray indicates that the wire is not connected to anything. This is not a big deal as you're in the process of building a circuit. But by the time you finish it, none of your wires should be blue or gray. (The unconnected legs of the OR gate will still be blue: That's fine.)
+
+
+ If you do have a blue or a gray wire after you think everything ought to be connected, then something is going wrong. It's important that you connect wires to the right places. Logisim draws little dots on the components to indicate where wires ought to connect. As you proceed, you'll see the dots turn from blue to light or dark green.
+
+
+ Once you have all the wires connected, all of the wires you inserted will themselves be light or dark green.
+
+ Logisim includes basic support for executing circuits from the command-line. This is intended both to help with scripted verification of circuit designs and to help instructors perform automated testing of students' solutions.
+
+
+ We'll start by seeing how to execute a circuit from the command line. For our example, we'll suppose we've built the below circuit in a file named adder-test.circ. It uses a two-bit adder as a subcircuit and iterates using a counter through all 16 possible inputs to it.
+
+
+
+
+
+ After this circuit has been built, we then execute Logisim from the command line, providing the filename of the project and the -tty option with the <table parameter.
+
+ Without bringing up any windows, Logisim loads the circuit and begins to execute it, ticking any clocks as fast as it can while completing the propagation between each tick. After each propagation is completed, Logisim loads the current values of the output pins; if any have changed from the previous propagation, then all values are displayed in tab-delimited format. If there is an output pin labeled with the special word halt, its output is not displayed — but once the pin's value reaches 1 after a propagation is completed, Logisim ends the simulation.
+
+
+ For our example, Logisim displays the table below. Because we have two output pins corresponding to the two inputs a and b into the two-bit adder, these outputs are included as the first two columns of the output. And there is another output pin sum corresponding to the two-bit adder's output, so it is the third column. The columns are ordered left-to-right according to the top-down ordering within the circuit.
+
+ In the classroom example, you will have many files that you wish to test for their equivalence, and you won't want to read the output for each of the student's solutions.
+
+
+ Building comparison into the circuit
+
+
+ One approach is to build a test circuit that does the comparison directly. Here, we create an additional circuit within the testing file that contains our solution circuit. In our overall testing circuit, we include both the subcircuit from master.circ and the subcircuit from the solution circuit located directly into the nested circuit. We wire it so that there is just one output, which is 1 as long as the two subcircuits agree.
+
+
+
+
+
+ Now we can simply run Logisim substituting each query file. For any correct solution, the only output will be "1".
+
+
+ Using redirection and shell scripts
+
+
+ If you're quite comfortable with the command line, you can build your own shell script to accomplish this. Here, we'll use redirection (the > operator) to save the output of each circuit into a file. For instance, we might issue the following two commands to collect the output of the master circuit and the query circuit.
+
+ Now we've created two different files. We can then compare the two output files using a program built for that purpose. Under Linux or MacOS X, you might want to use the cmp or diff command-line utilities. Under Windows, you might want to use command-line utilities fc or WinMerge.
+
+
+ To process several query files, you would like want to build a simple program such as a shell script to iterate through each and comparing the output. Here is how I would do it under Linux's bash:
+
+
+ RUN_TEST="java -jar logisim-filename.jar adder-test.circ -tty table"
+ ${RUN_TEST} > output-master.txt
+ for QUERY_FILE in query*.circ
+ do
+ if ${RUN_TEST} -sub ^master.circ ${QUERY_FILE} | cmp -s output-master.txt
+ then
+ echo "${QUERY_FILE} OK"
+ else
+ echo "${QUERY_FILE} different"
+ fi
+ done
+
+ There are a some additional options related to command-line execution.
+
+
+ The -load command-line parameter
+
+
+ A more complex circuit might include a RAM component that needs to be loaded with a program in order for the circuit to have anything to do. You can specify a memory image file at the command line, which will be loaded into any RAM component in the circuit before simulation begins. (This does not work when loading the GUI - it is only for command-line execution.)
+
+ The order of the parameters is not important (except the table parameter must be immediately after -tty, and the memory image's filename must be immediately after -load). The memory image file should be in Logisim's memory image format.
+
+
+ Logisim searches for RAM recursively, so this will still work if RAM is nested within a subcircuit. There is no way, though, to distinguish different RAM components: Logisim will attempt to load the same file into every RAM that it can find.
+
+
+ Options for the -tty parameter
+
+
+ In our examples thus far, we've always used -tty table to indicate that a table of output values should be displayed. You can customize the behavior in other ways by listing one or more options, separated by commas. For instance, you might write -tty table,halt,speed, and the program will perform all three behaviors listed below. (The order in which they are listed does not matter.)
+
+
+
+ halt
+
+
+
+ After the simulation ends, a one-line message is displayed explaining why the simulation ended. Error conditions - such as a detected oscillation - are displayed in any case.
+
+
+
+ speed
+
+
+
+ If you use speed in conjunction with -tty, then after completing the simulation Logisim will display a summary of how quickly the circuit was simulated, such as:
+
+
+ 714 Hz (509 ticks in 712 milliseconds)< /blockquote>
+
+ Note that displaying information during the simulation makes the simulation go much slower. As just one comparison, the same circuit and image ran at 714 Hz above with just the speed option but 490 Hz with the table option as well.
+
+
+
+
+ stats
+
+
+
+ Shows a tab-delimited table containing statistics about components used by the top-level "main" circuit in the project. The table includes four columns:
+
+
+
Unique: The number of times that component appears in the circuit's hierarchy, where each subcircuit within the hierarchy is counted only once.
+
+
Recursive: The number of times that component appears in the circuit's hierarchy, where we count each subcircuit as many times as it appears in the hierarchy.
+
+
Component: The name of the component.
+
+
Library: The name of the library from which the component came.
+
+
+
+ The distinction between "Unique" and "Recursive" is explained further under Project menu section. If the file uses circuits from a loaded Logisim library, those components are considered to be "black boxes": The contents of the library's circuits are not included in the unique and recursive counts.
+
+
+ (This feature can be useful for instructors who assign students to build projects using a subset of Logisim's libraries.)
+
+
+
+ table
+
+
+
+ (as already discussed)
+
+
+
+ tty
+
+
+
+ Any TTY components send their output to the display (standard output), and any information typed at the keyboard is sent to all Keyboard components in the circuit. These components are included even if they are nested deeply in the subcircuit hierarchy.
+
+ Now suppose we have two Logisim circuits that are supposed to do the same thing. As an instructor, you might have had students complete an assignment: You have one file containing your solution, but you have several student files containing their work. Maybe the assignment was to build a two-bit adder.
+
+
+ I'll imagine that we have two files, named master.circ and query.circ. Each file contains a circuit named Adder2 (it's important that the circuit to test be named exactly the same), whose appearance is the following.
+
+
+
+
+
+
+ Adder2 in master.circ
+
+
+ Adder2 in query.circ
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ As you can see, the master circuit uses Logisim's built-in adder, while the query circuit uses two subcircuits representing a half adder and a full adder (which themselves are built up of simple gates). For the purpose of our example, the query circuit has a stupid error: The carry from the half adder is not connected into the full adder.
+
+
+ We build our testing circuit into a different file test.circ. There, we load master.circ as a Logisim Library | Project |→| Load Library |→ | Logisim Library |, and we insert its 2-bit adder as a subcircuit. We could execute this circuit directly to get the desired output for a perfect solution.
+
+ But we want to execute the circuit using query.circ rather than master.circ as the loaded library. The naive approach would be to open Logisim and load that library instead; or you might simply remove the master.circ file and rename query.circ to be named master.circ instead. But Logisim includes a handy -sub option that temporarily replace one file by another during that session — without making any changes on disk.
+
+ The output you would see from this is shown below; it is of course different from what we saw in the previous section because the library common to adder2 has been replaced in the test circuit by that of query.circ erroneous.
+
+ From the Test Vector Window you can load a test vector from a file, and Logisim will start running tests on the current circuit. is only one test vector window for the project, and the table will change to reflect whichever circuit is being simulated in the project window. Note, however, that the Test Vector module runs a separate copy of the circuit simulator, and so does not interfere with, and is not influenced by, the simulation in the project window.
+
+
+ For the example we will test the circuit below. This circuit gives the results of five logical functions from two inputs. It has an error the bottom NAND gate should be an AND port.
+
+ To start the test, select the menu | Simulate |→| Test Vector | then use the button Load Vector. Select the file of vectors that you have built. The simulation is executed immediately and a table is displayed with the result.
+
+
+
+
+
+ Any incorrect output will be indicated in red. Lines with incorrect outputs are sorted at the top of the window.
+
+
+ The file format is simple. The first line contains column headers that correspond to the names of the signals. If the bit width is greater than 1 then it is necessary to specify it in square brackets. Example C[8]. The data for each test situation is in the following lines. Blank lines are ignored. Anything following a "#" character is a comment.
+
+
+ The remaining rows list each value separated by a space or tab. Values can be in hexadecimal, octal, binary, or signed decimal. The hexadecimal values must have the prefix < tt="">. Octal values must have the prefix "0o". inary and decimal are be distinguished by the number of digits: binary values must always have exactly as many digits as the width of the column; decimal values must always have fewer, should not have leading zeros, and may have a negative sign.
+
+ Depending on the representation of values in hexadecimal, octal or binary, the lowercase "x" is used to specify four, three or one "unimportant" bits. For example 101xx is a binary value of five bits, with the last two unspecified bits, and 0x1ax5 is a hexadecimal value with two unspecified four-bit bits. Such wildcards can not be used in decimal notation.
+
+
+ Command line: To facilitate automated testing, the test vector feature can be run from the command line as follows:
+
This component adds two values coming in via the west inputs and
+outputs the sum on the east output. The component is designed so that it
+can be cascaded with other adders to provide add more bits than is
+possible with a single adder: The carry-in input provides a
+one-bit value to be added into the sum also (if it is specified), and a
+carry-out output provides a one-bit overflow value that can be fed to
+another adder.
+
+
If either of the addends contains some floating bits or some error
+bits, then the component will perform a partial addition. That is, it
+will compute as many low-order bits as possible. But above the floating
+or error bit, the result will have floating or error bits.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches Data Bits attribute)
+
One of the two values to add.
+
+
West edge, south end (input, bit width matches Data Bits attribute)
+
The other of the two values to add.
+
+
North edge, labeled c in (input, bit width 1)
+
A carry value to add into the sum. If the value is unknown (i.e.,
+floating), then it is assumed to be 0.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The lower dataBits bits of the sum of the two values
+coming in the west edge, plus the cin
+bit.
+
+
South edge, labeled c out (output, bit width 1)
+
The carry bit computed for the sum. If the values added together as
+unsigned values yield a result that fits into dataBits
+bits, then this bit will be 0; otherwise, it will be 1.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the values to be added and of the result.
The component determines how many 1 bits are in its input(s) and emits the
+total number of 1 bits on its output. For example, given the 8-bit input 10011101,
+the output would be 5, since there are five 1-bits in the input
+(the first, the last, and a string of three bits in the middle).
+
+
If any of the input bits are floating or error values, then the output will
+contain error bits in the output corresponding to the range of possible outputs
+depending on whether those floating/error values are counted as zeroes or ones.
+For instance, if the 14-bit input is 111x10110x1101, then the output must be
+at least 9 (if the x's are interpreted as zeroes)
+and at most 11 (if they are interpreted as ones).
+Thus, the output will be 10EE: The upper two bits will be 1 and 0 since all integers
+between 9 and 11 have 1 and 0 as their top two bits, but the lower two bits are EE
+since integers between 9 and 11 vary within these bits.
+
+
Pins
+
+
+
+
West edge (inputs, bit width matches Data Bits attribute)
+
The inputs whose 1 bits are to be counted. The number of inputs is based
+on the Number of Inputs attribute.
+
+
East edge (output, bit width computed as described below)
+
The number of input bits which are 1. The bit width of the output is the
+minimum number of bits to store the maximum possible value (which would be
+the product of the Data Bits attribute and the Number of Inputs attribute).
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Number of Inputs attribute and
+Alt-0 through Alt-9 alter its Data Bits attribute.
The component takes a multi-bit input and determines the the index of a bit,
+where the index is computed by counting from 0 as the lowest-order bit.
+Exactly which index it computes depends on the Type attribute, as illustrated
+by the examples in the below table for the 8-bit sample input 11010100.
+
+
+
Type
Output for 11010100
+
+
Lowest-order 1
2
+
Highest-order 1
7
+
Lowest-order 0
0
+
Highest-order 0
5
+
+
+
For the lowest-order 1, the output is 2 because if you index the bits
+starting from 0 for the lowest-order bit, the first 1 you will find is
+at index 2. (The bits at indices 0 and 1 are both 0.)
+For the highest-order 1, the output is 7 because the topmost 1 bit is at index 7
+(again counting from the lowest-order bit as 0).
+
+
The component's output on the south edge indicates whether the desired bit
+was found at all. In the above examples involving the input 11010100,
+the south output is 1 in all cases.
+But if the input were 00000000 and the component is to find the
+lowest-order 1, then the south output would be 0 — and the output on the
+east edge would be 0 as well.
+
+
If while searching for the desired value, a value that is neither 0 or 1 is
+found (the bit could be floating or an error value),
+then both outputs will consist entirely of error bits.
+Note that this occurs only if the problematic bit is encountered before finding
+the desired bit: For the input x1010100, the output would still be 2 if
+the lowest-order 1 is desired; but we would get error values if the component's
+type indicates to search for the highest-order 1 or the highest-order 0, since
+there is an erroneous bit in a higher-order bit than either the highest-order 0
+or the highest-order 1.
+
+
Pins
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The multibit input that is to be searched for the desired bit.
+
+
East edge (output, bit width computed as described below)
+
The index of the desired bit, counting from 0 for the lowest-order bit.
+The bit width is the
+minimum number of bits to store the maximum possible index, which is one
+less than the value of the Data Bits attribute.
+
+
South edge (output, bit width 1)
+
1 if the desired bit is found, 0 if all input bits are the inverse of the
+desired bit, and the error value if a non-0, non-1 value is found before the
+desired bit.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the input.
+
+
Type
+
Indicates which bit to search for — the lowest-order 0,
+the highest-order 0, the lowest-order 1, or the highest-order 1.
Compares two values, either as unsigned values or as two's-complement
+values, depending on the Numeric Type attribute. Normally, one of the
+outputs will be 1, and the other two outputs will be 0.
+
+
The comparison is performed starting at the most significant bits in
+each number and descending downward in parallel until a location is
+found where the two values disagree. If, however, an error value or
+a floating value is encountered during this descent, then all outputs
+will match that error or floating value.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches Data Bits attribute)
+
The first of the two values to be compared.
+
+
West edge, south end (input, bit width matches Data Bits attribute)
+
The second of the two values to be compared.
+
+
East edge, labeled > (output, bit width 1)
+
1 if the first input is greater than the second input, 0 if
+the first input is less than or equal the second input.
+
+
East edge, labeled = (output, bit width 1)
+
1 if the first input equals the second input, 0 if
+the first input is not equal the second input.
+
+
East edge, labeled < (output, bit width 1)
+
1 if the first input is less than the second input, 0 if
+the first input is greater than or equal the second input.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
This component divides two values coming in via the west inputs and
+outputs the quotient on the east output. The component is designed so
+that it can be cascaded with other dividers to provide support a
+dividend with more bits than
+is possible with a single divider: The upper input provides the
+upper dataBits bits of the dividend (if it is specified at
+all), and the rem bits provide the remainder, which can be
+fed as the upper input into another divider.
+
+
If the divisor is 0, then no division is performed (i.e., the divisor
+is assumed to be 1).
+
+
The divider essentially performs unsigned division. That is, the
+remainder will always be between 0 and divisor-1. The
+quotient will always be an integer so that
+
+quotient * divisor + remainder
+= dividend .
+
+If, however, the quotient does not fit into
+dataBits bits, then only the lower dataBits bits
+will be reported. The component does not provide any method for
+accessing the upper dataBits bits.
+
+
If either of the operands contains some floating bits or some error
+bits, then the component's outputs will be either entirely floating or
+entirely error values.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches Data Bits attribute)
+
The lower dataBits bits of the dividend (that is, the
+first operand for the division).
+
+
West edge, south end (input, bit width matches Data Bits attribute)
+
The divisor (that is, the second operand for the division)
+
+
North edge, labeled upper (input, bit width matches Data Bits attribute)
+
The upper dataBits bits of the dividend (that is, the
+first operand for the division).
+
+
East edge (output, bit width matches Data Bits attribute)
+
The lower dataBits bits of the quotient, as specified
+above.
+
+
South edge, labeled rem (output, bit width matches Data Bits attribute)
+
The remainder of the division. This value will always be between 0
+and divisor-1.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the values to be divided and of the result.
This component multiplies two values coming in via the west inputs
+and outputs the product on the east output. The component is designed so
+that it can be cascaded with other multipliers to multiply a
+multiplicand with more bits than is possible with a single multiplier:
+The carry-in input provides a multi-bit value to be added into the
+product (if it is specified), and a carry-out output provides the upper
+half of the product result, which can be fed into another
+multiplier.
+
+
If the multiplicand, the multiplier, or the carry-in input contain
+some floating bits or some error bits, then the component will perform a
+partial multiplication. That is, it will compute as many low-order bits
+as possible. But above the floating or error bit, the result will have
+floating or error bits. Note that if the carry-in input is completely
+floating, then it will be assumed to be all-zeroes.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches Data Bits attribute)
+
The multiplicand (that is, the first of the two numbers to
+multiply).
+
+
West edge, south end (input, bit width matches Data Bits attribute)
+
The multiplier (that is, the second of the two numbers to multiply).
+
+
North edge, labeled c in (input, bit width matches Data Bits attribute)
+
A carry value to add into the product. If all bits of the value are
+unknown (i.e., floating), then they are assumed to be 0.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The lower dataBits bits of the product of the two values
+coming in the west edge, plus the cin
+value.
+
+
South edge, labeled c out (output, bit width matches Data Bits attribute)
+
The upper dataBits bits of the product.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the values to be multiplied and of the result.
Computes the two's-complement negation of the input. This negation
+is performed by maintaining all the lower-order bits up to the
+lowest-order 1, and complementing all bits above that.
+
+
If the value to be negated happens to be the least negative value,
+then its negation (which cannot be represented in two's-complement
+form), is still the least negative value.
+
+
Pins
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The value to negate.
+
+
East edge, labeled -x (output, bit width matches Data Bits attribute)
+
The negation of the input. If the input happens to be the least
+negative value representable in dataBits bits, however, then
+the output matches the input.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the component's input and output.
This component includes two inputs, data and dist, and
+it has one output, which is the result of shifting data by
+dist places. Both data and output have the same number of
+bits in them. The component supports the following shift types:
+
+
+
+
Logical Left: All bits in data are shifted up dist places,
+with the bottom dist places filled with 0's. For example,
+11001011 logically shifted left twice is 00101100. (The top two ones are lost.)
+
+
Logical Right: All bits in data are shifted down dist
+places, with the upper dist places filled with 0's. For example,
+11001011 logically shifted right twice is 00110010. (The bottom two ones are
+lost.)
+
+
Arithmetic Right: All bits in data are shifted down dist
+places, with the upper dist places filled with repetitions of
+whatever the uppermost bit in data. For example, 11001011
+arithmetically shifted right twice is 11110010.
+
+
Rotate Left: All bits in data are shifted up dist
+places, with the top dist places wrapped around into the bottom.
+For example, 11001011 rotated left twice is 00101111.
+
+
Rotate Right: All bits in data are shifted down dist
+places, with the bottom dist places wrapped around into the top.
+For example, 11001011 rotated right twice is 11110010.
+
+
+
+
Note that if dist contains any floating or error inputs, then
+the output is composed entirely of error values, since there is no way to
+guess how far to shift the input.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches the Data Bits attribute)
+
The value to be shifted.
+
+
West edge, south end (input, bit width is computed as below)
+
The number of bits by which to shift the data input.
+This input should have as many bits as is the minimum number to indicate
+any shift distance from 0 up to one less than Data Bits; that is, it should
+be the ceiling of the base-2 logarithm of Data Bits. For example, if Data Bits
+were 8, this input would require 3 bits; but if it were 9, it would require
+4 bits.
+
+
East edge (output, bit width matches the Data Bits attribute)
+
The result of shifting the input value by the input distance.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the data input and of the output.
+
+
Shift Type
+
One of the five possible shift types as outlined above (Logical Left,
+Logical Right, Arithmetic Right, Rotate Left, Rotate Right).
This component subtracts values coming in via the west inputs
+(the upper minus the lower) and outputs the difference on the east
+output. The component is designed so that it can be cascaded with other
+subtractors to provide subtract more bits than is possible with a single
+subtractor: The borrow-in input provides a one-bit value to be borrowed
+out of the difference (if the borrow-in input is specified), and a
+borrow-out output indicates whether the component needs to borrow an
+upper-order bit to complete the subtraction without underflow (assuming
+unsigned subtraction).
+
+
Internally, the subtractor simply performs a bitwise NOT on the
+subtrahend, and add this to the minuend along with the NOT of the
+borrow-in input. (The minuend is the first operand (upper
+input) to the subtraction, and the subtrahend is the second
+(lower input). I happen to like the antiquated terms.)
+
+
If either of the operands contains some floating bits or some error
+bits, then the component will perform a partial subtraction. That is, it
+will compute as many low-order bits as possible. But above the floating
+or error bit, the result will have floating or error bits.
+
+
Pins
+
+
+
+
West edge, north end (input, bit width matches Data Bits attribute)
+
The minuend of the subtraction; that is, the number from which to
+subtract.
+
+
West edge, south end (input, bit width matches Data Bits attribute)
+
The subtrahend of the subtraction; that is, the number to subtract
+from the minuend.
+
+
North edge, labeled b in (input, bit width 1)
+
If 1, then 1 is borrowed out of the difference. If the value is
+unknown (i.e., floating), then it is assumed to be 0.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The lower dataBits bits of the difference of the two
+values coming in the west edge, minus the
+bin bit.
+
+
South edge, labeled b out (output, bit width 1)
+
The borrow bit computed for the difference. If the values subtracted
+as unsigned values yield a negative value, then this bit will be 1;
+otherwise, it will be 0.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the values to be subtracted and of the result.
The Edit tool allows the user to rearrange existing components and to add
+wires. Exactly what the tool does depends on where the user presses the mouse
+on the canvas.
+
+
+
+
When the mouse is over a wiring point for an existing component,
+or if it is atop a current wire, the Edit Tool will display a small green circle
+around the mouse's location. Pressing the button there initiates the addition of
+a new wire. But if the user doesn't drag the mouse far enough to initiate a
+wire before releasing the button, the press is treated as a mouse click, and so
+the wire is simply added into the current selection.
+
+
The bit width of an added wire is inferred from the components to which it
+is connected. If it is not attached to any components, the wire will be drawn
+gray to indicate that its bit width is unknown; if the components at the
+locations that the wire helps to connect disagree on the bit width, then the
+wire will be drawn orange to indicate the conflict, and the wire will in fact
+refuse to carry any values at all until the user resolves the conflict.
+
+
All wires in Logisim are either horizontal or vertical, never diagonal.
+
+
Wires are non-directional; that is, they carry values from
+either endpoint to the other. Indeed, a wire can carry values
+in both directions simultaneously: In the below example, a bit flows from the
+upper input at left through the center wire, then it circles back through the
+center wire, and then it circles forward again through the center wire before
+reaching the output at lower right.
+
+
+
A single drag of the mouse can create multiple wire segments. The
+precise process is a little confusing in its description; but it works
+quite intuitively in practice: If you request a particular wire segment
+using the Wiring Tool, that segment will be split apart wherever it hits
+a pin for an existing component, or wherever it hits the endpoint of an
+existing wire segment. Also, if an endpoint of any of the new wire
+segments hit somewhere in the middle of an existing wire, then that wire
+will be split into multiple segments itself.
+
+
You can also shorten or delete an existing wire segment by initiating a drag
+at the terminus of the segment and then drawing backwards across the segment.
+During the drag, the shortening is indicated by drawing a white line over of the
+portion of the wire that will be removed.
+
+
Some components draw short stubs to which wires can connect, such as the
+OR gate and controlled buffer. Logisim will
+silently correct attempts to create wires that slightly overshoot the
+stub's end.
+
+
If, however, the user presses the Alt key at a point in the middle of
+the wire, then the green circle will disappear. A mouse press selects the wire,
+and a mouse drag moves it.
+
+
Pressing the mouse button while it is within a currently selected
+component begins a drag moving all elements of the selection.
+
+
By default, Logisim will compute a way to add new wires
+so that no existing connections are lost during the move.
+(Sometimes it will delete or shorten existing wires.)
+If you're performing a move where you do not want these changes to be made,
+you can press the shift key during the move.
+If you want to disable this behavior entirely,
+go to Project > Options, select the Canvas tab,
+and uncheck the Keep Connections When Moving box;
+in this case, the connections are computed only when the shift key is down.
+
+
Dragging a selection can lead to unexpected behavior from wires: If
+you drag a selection including some wires on top of some other wires,
+all wires are merged, and the merged wires are placed into the
+selection. As a result, if you drag the selection a second time, the
+wires previously at the location will not be left behind. This behavior
+is necessary to keep with the intuitive behavior of wires in Logisim, where
+wires never overlap. And
+it does not normally constitute a major problem: Logisim will draw the
+full selection in the midst of dropping, and you should not drop it
+until you are sure it is in the correct location.
+
+
Pressing the mouse within an unselected component (but not at one of
+the component's wiring points) drops all components from the current selection
+and selects instead the component(s) containing the clicked location.
+
+
Shift-clicking the mouse within a component toggles that component's
+presence within the selection. If multiple components include the same
+location, all components' presence will be toggled.
+
+
Dragging the mouse starting at a location not contained within any
+components drops all components from the current selection and
+initiates a rectangular selection.
+All component(s) contained by the rectangle will be placed into the
+selection.
+
+
Shift-dragging the mouse starting at a location not contained
+within any components initiates a rectangular selection.
+The presence in the selection of all component(s) contained by the
+rectangle will be toggled.
+
+
However, if the Alt key is pressed at a location not contained within
+any components, this initiates the addition of a new wire. A small green circle
+is drawn in such a circumstance to indicate this.
+
+
+
+
After selecting the desired items in the selection, you can of course
+cut/copy/paste/delete/duplicate all the items via the
+Edit menu.
+
+
Some keys have an effect with the Edit Tool.
+
+
+
+
The arrow keys change the Facing attribute for all components in the
+selection that have such an attribute.
+
+
The Delete and Backspace keys will delete everything in the selection
+from the circuit.
+
+
The Insert and MenuKey-D keys will create a duplicate of the currently
+selected components.
+
+
+
+
Logisim's behavior when duplicating a selection or pasting the clipboard into
+a circuit is somewhat peculiar: It will not immediately place the components into the
+circuit; instead, the selection will be a collection of "ghosts," which
+will be dropped into the circuit as soon as they are either dragged to
+another location or removed from the selection. (This peculiar behavior
+is necessary because pasting will otherwise merge the wires of the
+selection into the current circuit at once, and the wires there
+previously will be dragged with the pasted clipboard if the user wants
+to move the pasted components somewhere else.)
+
+
Attributes
+
+
None. Selecting a component, though, will display its attributes.
+With multiple components selected, attributes shared by all are shown,
+blank if they have different values and otherwise with the value they
+all have in common. (Wires are ignored if there are any non-wires in
+the selection.) Changes to the attribute value affect all selected
+components.
This is a simple text label that can be placed anywhere in the
+circuit. It does not interact with values traveling through the circuit
+in any way, except inasmuch as it will be visible when the circuit is
+drawn.
+
+
In contrast to all other components in the current built-in
+libraries, label components can be placed anywhere on the canvas;
+they do not snap to the grid.
+
+
Pins
+
+
None.
+
+
Attributes
+
+
+
+
Text
+
The text appearing in the label. This value can be edited in the
+attribute table or, using the text tool, on the canvas.
+
+
Font
+
The font to use when drawing the label.
+
+
Horizontal Alignment
+
The horizontal positioning technique for the text relative to the label's official location
+(where the mouse was clicked in creating the label). "Left"
+means that the text should be drawn so that its left edge
+is at the location; "right" means that the text should be
+drawn so that its right edge is at the location; and "center" means that
+the text should be drawn so that its center (horizontally) is at the
+location.
+
+
Vertical Alignment
+
The vertical positioning technique for the text relative to the
+label's official location (where the mouse was clicked in creating the
+label). "Base" means that the baseline should intersect the location;
+"Top" means that the text's top should intersect the location; "Bottom"
+means that the text's bottom should intersect the location; and "Center"
+means that the text should be centered (vertically) at the location.
+
+
The text's top and bottom is computed based on the font's
+standard ascent and descent values; thus, even if the actual text
+contains no tall letters (such as b) or descending letters
+(such as g), it is assumed to contain such letters for the
+purposes of vertical positioning.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the text appearing within the label to be edited.
The menu tool permits the user to pull up a pop-up menu for
+components that already exist. By default, right-clicking or
+control-clicking a component will bring up this pop-up menu; however, the Mouse tab of the project options allows a user to
+configure the mouse buttons to work differently.
+
+
The pop-up menu for most components has two items.
+
+
+
Delete: Removes the component from the circuit.
+
+
Show Attributes: Places the component's attributes into the
+window's attribute table, so that the attribute values can be viewed and
+changed.
+
+
+
For some components, however, the menu has additional items.
+Subcircuits (that is, instances of using one circuit as a "black box"
+within another) are one example of this: In addition to the above two
+items, the pop-up menu includes another item.
+
+
+
View XXX: Changes the circuit layout being viewed and
+edited to be the subcircuit's layout instead. The values seen in the
+layout will be part of the same hierarchy as those of the supercircuit.
+(See the
+`Debugging subcircuits'
+section of the User's Guide.)
+
+
+
Other components may extend the pop-up menu also.
+In the built-in libraries of the current version of Logisim, the only
+such components are RAM and
+ROM.
The Poke Tool is for manipulating the current values associated with
+components. The precise behavior of the Poke Tool varies depending on
+which component is clicked; this behavior is documented in the `Poke
+Tool Behavior' section of each individual component.
+The following components all have support for the Poke Tool.
Allows individual components to be placed into the current selection.
+There are a number of actions possible with this tool.
+
+
+
Pressing the mouse button while it is within a currently selected
+component begins a drag moving all components of the selection.
+
+
By default, Logisim will compute a way to add new wires
+so that no existing connections are lost during the move.
+(Sometimes it will delete or shorten existing wires.)
+If you're performing a move where you do not want these changes to be made,
+you can press the shift key during the move.
+If you want to disable this behavior entirely,
+go to Project > Options, select the Canvas tab,
+and uncheck the Keep Connections When Moving box;
+in this case, the connections are computed only when the shift key is down.
+
Dragging a selection can lead to unexpected behavior from wires: If
+you drag a selection including some wires on top of some other wires,
+all wires are merged, and the merged wires are placed into the
+selection. As a result, if you drag the selection a second time, the
+wires previously at the location will not be left behind. This behavior
+is necessary to keep with the expected behavior of wires in Logisim. And
+it does not normally constitute a major problem: Logisim will draw the
+full selection in the midst of dropping, and you should not drop it
+until you are sure it is in the correct location.
+
+
Otherwise, clicking the mouse within a component drops all
+components from the current selection and selects instead the
+component(s) containing the clicked location.
+
+
Shift-clicking the mouse within a component toggles that component's
+presence within the selection. If multiple components include the same
+location, all components' presence will be toggled. None of this will
+happen, though, if shift-clicking is mapped to another tool instead (via
+the project options window's Mouse
+tab).
+
+
Dragging the mouse starting at a location not contained within any
+components drops all components from the current selection and
+initiates a rectangular selection.
+All component(s) contained by the rectangle will be placed into the
+selection.
+
+
Shift-dragging the mouse starting at a location not contained
+within any components initiates a rectangular selection.
+The presence in the selection of all component(s) contained by the
+rectangle will be toggled. This will not happen, though, if
+shift-clicking is mapped to another tool instead.
+
+
+
+
After selecting the desired items in the selection, you can of course
+cut/copy/paste/delete all the items via the Edit menu.
+
+
Logisim's behavior when pasting the clipboard into a circuit is
+somewhat peculiar: It will not immediately place the components into the
+circuit; instead, the selection will be a collection of "ghosts," which
+will be dropped into the circuit as soon as they are either dragged to
+another location or removed from the selection. (This peculiar behavior
+is necessary because pasting will otherwise merge the wires of the
+selection into the current circuit at once, and the wires there
+previously will be dragged with the pasted clipboard if the user wants
+to move the pasted components somewhere else.)
+
+
Attributes
+
+
None. Selecting a component, though, will display its attributes.
+With multiple components selected, attributes shared by all are shown,
+blank if they have different values and otherwise with the value they
+all have in common. (Wires are ignored if there are any non-wires in
+the selection.) Changes to the attribute value affect all selected
+components.
The text tool allows you to create and edit labels associated with
+components. Which components support labels are indicated in the 'Text
+Tool Behavior' section of their documentation. As of the current
+release, the following components in the built-in libraries support labels.
For components that can take a label but have none assigned to it currently,
+you can click anywhere within the component to add a label. If there is already
+a label, you need to click within the label. If you click at a point where there
+is not currently a label to be edited, Logisim will initiate the addition of a
+new Label component.
+
+
In the current version of Logisim, text editing features are
+still fairly primitive.
+Selections of a region of text within a label is impossible.
+There is no way to insert a line break into a label.
+
+
Attributes
+
+
The attributes for the tool are the same as for the label component. These attributes have no effect
+when editing the label on an existing component, but they are imparted
+to any labels created using the text tool.
+
+
Clicking on a component supporting the Text Tool will
+display that component's attributes.
The wiring tool is the tool for creating wire segments that carry
+values from one endpoint to another. The bit width of these values can
+be anything; exactly which bit width is automatically inferred from the
+components to which the wires are ultimately attached. If it is not
+attached to any components, the wire will be drawn gray to indicate that
+its bit width is unknown; if the components at the locations that the
+wire helps to connect disagree on the bit width, then the wire will be
+drawn orange to indicate the conflict, and the wire will in fact refuse
+to carry any values at all until the user resolves the conflict.
+
+
A single drag of the mouse can create multiple wire segments. The
+precise process is a little confusing in its description; but it works
+quite intuitively in practice: If you request a particular wire segment
+using the Wiring Tool, that segment will be split apart wherever it hits
+a pin for an existing component, or wherever it hits the endpoint of an
+existing wire segment. Also, if an endpoint of any of the new wire
+segments hit somewhere in the middle of an existing wire, then that wire
+will be split into multiple segments itself.
+
+
For some components that draw short stubs to which wires can connect
+(such as an OR gate or a controlled buffer), Logisim will
+silently correct attempts to create wires that slightly overshoot the
+stub's end.
+
+
You can also shorten an existing wire segment using the Wiring Tool,
+using a drag that starts or ends at a terminus of the segment, and that
+overlaps the existing segment.
+
+
All wires in Logisim are either horizontal or vertical.
+
+
Wires are also non-directional; that is, they carry values from
+either endpoint to the other. Indeed, a wire can carry values
+in both directions simultaneously; the center wire in the below example
+is doing this.
+
+
+
Attributes
+
+
The wiring tool does not itself have attributes, but the wires that
+it creates do.
+
+
+
+
Direction
+
Indicates whether the wire is horizontal or vertical.
+The value of this attribute cannot be changed.
+
+
Length
+
Indicates how many pixels long the wire is.
+The value of this attribute cannot be changed.
+
+
+
+
Poke Tool Behavior
+
+
When you click an existing wire segment using the Poke Tool, Logisim
+displays the current value traveling through that wire.
+The behavior is particularly useful for multi-bit wires, whose black
+color provide no visual feedback about what value the wire is
+carrying.
+
+
For multi-bit values, you can configure exactly how the value
+is displayed (in binary, decimal, or hexadecimal, for example) using
+the Layout
+pane of the Logisim Preferences dialog box.
+
+
The AND, OR, NAND, and NOT gates each compute the respective
+function of the inputs, and emit the result on the output.
+
+
By default, any inputs that are left unconnected are ignored
+— that's if the input truly has nothing attached to it,
+not even a wire.
+In this way, you can insert a 5-input gate but only attach two inputs,
+and it will work as a 2-input gate;
+this relieves you from having to worry about configuring
+the number of inputs every time you create a gate.
+(If all inputs are unconnected, the output is the error value X.)
+Some users, though, prefer that Logisim insist that all inputs be connected,
+since this is what corresponds to real-world gates.
+You can enable this behavior by going to the Project > Options… menu item,
+selecting the Simulation tab, and
+selecting Error for undefined inputs for
+Gate Output When Undefined.
+
+
The two-input truth table for the gates is the following.
+(The letter X represents the error value,
+and the letter Z represents the floating value.)
+
+
+
+
AND
+
0
1
X/Z
+
0
0
0
0
+
1
0
1
X
+
X/Z
0
X
X
+
+
OR
+
0
1
X/Z
+
0
0
1
X
+
1
1
1
1
+
X/Z
X
1
X
+
+
NAND
+
0
1
X/Z
+
0
1
1
1
+
1
1
0
X
+
X/Z
1
X
X
+
+
NOR
+
0
1
X/Z
+
0
1
0
X
+
1
0
0
0
+
X/Z
X
0
X
+
+
+
In short, these components work as expected as long as all inputs
+are either 0 or 1.
+If an input is neither 0 nor 1 (it is floating or it is the error value)
+then the component treats it as both 0 and 1:
+If the output would be the same both ways
+(as when an AND gate has one input that is definitely 0
+and a questionable second input), that will be the output value;
+but if the output changes depending on whether it is 0 or 1,
+the output is the error value.
+
+
The multi-bit versions of each gate will perform its one-bit
+transformation bitwise on its inputs.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge (inputs, bit width according to Data Bits attribute)
+
The inputs into the component. There will be as many of these as
+specified in the Number of Inputs attribute.
+
+
Note that if you are using shaped gates, the west side of OR and NOR
+gates will be curved. Nonetheless, the input pins are in a line. Logisim
+will draw short stubs illustrating this; and if you overshoot a stub, it
+will silently assume that you did not mean to overshoot it. In "printer
+view", these stubs will not be drawn unless they are connected to
+wires.
+
+
East edge (output, bit width according to Data Bits attribute)
+
The gate's output, whose value is computed based on the current
+inputs as described above.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Number of Inputs attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its inputs).
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
+
+
Gate Size
+
Determines whether to draw a wider or narrower version of the
+component. This does not affect the number of inputs, which is specified
+by the Number of Inputs attribute. However, if shaped gates are selected,
+then the gate will be drawn with wings to accommodate additional inputs
+beyond what the shape naturally accommodates.
+
+
Number of Inputs
+
Determines how many pins to have for the component on its west
+side.
+
+
Output Value
+
Indicates how false and true results should be translated into output values.
+By default, false is indicated by a low voltage (0) and true by a high voltage (1),
+but one or the other can be replaced by a high-impedance (floating) value
+instead. This allows wired-or and wired-and connections, as illustrated below:
+At left, the buffers' Output Value attribute is floating/1 and the resistor pulls to 0,
+giving wired-or behavior;
+at right, the buffers' Output Value attribute is 0/floating and the resistor pulls to 1,
+giving wired-and behavior.
+
+
+
+
Label
+
The text within the label associated with the gate.
+
+
Label Font
+
The font with which to render the label.
+
+
Negate x
+
If yes, the input is negated before it is fed into the gate.
+The inputs are counted top-down if the facing is east or west,
+and they are counted left-to-right if the facing is north or south.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the gate to be edited.
The buffer simply passes through to its right output whatever input
+it receives on the left side.
+The truth table for a one-bit buffer is the following.
+
+
x
out
+
0
0
+
1
1
+
+
If the input is unspecified (i.e., floating), then the output will also be
+unspecified - unless the "Gate Output When Undefined" option is "Error for
+undefined inputs," in which case the output is an error. If the input is an
+error value, then the output will also be.
+
+
Buffers are the most useless of the gate components
+provided in Logisim; its presence in the Gates library is just as much a
+matter of completeness (a component for each possible
+one-input truth table) as it is a matter of providing useful
+functionality. Still, it can be occasionally useful to ensure that
+values propagate in only one direction along a wire.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge (input, bit width according to Data Bits attribute)
+
The input into the component.
+
+
East edge (output, bit width according to Data Bits attribute)
+
The output, which always matches the input into the left side.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
+
+
Output Value
+
Indicates how false and true results should be translated into output values.
+By default, false is indicated by a low voltage (0) and true by a high voltage (1),
+but one or the other can be replaced by a high-impedance (floating) value
+instead. This allows wired-or and wired-and connections, as illustrated in
+the AND/OR/NAND/NOR Gate documentation.
+
+
Label
+
The text within the label associated with the gate.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the gate to be edited.
The controlled buffer and inverter, often called three-state
+buffers/inverters, each have a one-bit "control"
+input pin on the south side. The value at this control pin affects how
+the component behaves:
+
+
+
When the value on this pin is 1,
+then the component behaves just like the respective component (a buffer or a inverter (NOT
+gate)).
+
+
When the value is 0 or unknown (i.e., floating), then the
+component's output is also floating.
+
+
When the value is an error value (such as would occur when two
+conflicting values are being fed into the input), then the output is an
+error value.
+
+
+
+
Controlled buffers can be useful when you have a wire (often called a
+bus) whose value should match the output of one of several
+components. By placing a controlled buffer between each component
+output and the bus, you can control whether that component's output is
+fed onto the bus or not.
+
+
Pins (assuming component faces east, control line right-handed)
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The component input that will be used to compute the output if the
+control input is 1.
+
+
South edge (input, bit width 1)
+
The component's control input.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The component's output, which will be floating if the control input
+is 0 or floating, the error value if the control input is the error
+value, and will be computed based on the west-side input if the control
+input is 1.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
+
+
Gate Size
+
(Controlled inverter only) Determines whether to draw a larger or a smaller
+version of the component.
+
+
Control Line Location
+
The location of the control line, imagining we are facing the output
+from the input: If the component faces east and is right-handed,
+the control line is to the south; but if it is left-handed,
+the control line is to the north.
+
+
Label
+
The text within the label associated with the gate.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the gate to be edited.
The NOT Gate emits the complement of whatever input
+it receives.
+The truth table for a NOT gate is the following.
+
+
x
out
+
0
1
+
1
0
+
+
If the input is unspecified (i.e., floating), then the output will also be
+unspecified - unless the "Gate Output When Undefined" option is "Error for
+undefined inputs," in which case the output is an error. If the input is an
+error value, then the output will also be.
+
+
A multi-bit NOT gate will perform the above transformation bitwise on
+its input.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge (input, bit width according to Data Bits attribute)
+
The component's input.
+
+
East edge (output, bit width according to Data Bits attribute)
+
The output, whose value is the complement of the input value.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Data Bits
+
The bit width of the component's input and output.
+
+
Gate Size
+
Determines whether to draw a larger or a smaller version of the
+component.
+
+
Output Value
+
Indicates how false and true results should be translated into output values.
+By default, false is indicated by a low voltage (0) and true by a high voltage (1),
+but one or the other can be replaced by a high-impedance (floating) value
+instead. This allows wired-or and wired-and connections, as illustrated in
+the AND/OR/NAND/NOR Gate documentation.
+
+
Label
+
The text within the label associated with the gate.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the gate to be edited.
The XOR, XNOR, Even Parity, and Odd Parity gates each compute
+the respective function of the inputs, and emit the result on the
+output.
+
+
By default, any inputs that are left unconnected are ignored
+— that's if the input truly has nothing attached to it,
+not even a wire.
+In this way, you can insert a 5-input gate but only attach two inputs,
+and it will work as a 2-input gate;
+this relieves you from having to worry about configuring
+the number of inputs every time you create a gate.
+(If all inputs are unconnected, the output is the error value X.)
+Some users, though, prefer that Logisim insist that all inputs be connected,
+since this is what corresponds to real-world gates.
+You can enable this behavior by going to the Project > Options… menu item,
+selecting the Simulation tab, and
+selecting Error for undefined inputs for
+Gate Output When Undefined.
+
+
The two-input truth table for the gates is the following.
+
+
x
y
XOR
+
XNOR
Odd
Even
+
0
0
+
0
1
+
0
1
+
0
1
+
1
0
+
1
0
+
1
0
+
1
0
+
1
0
+
1
1
+
0
1
+
0
1
+
+
As you can see, the Odd Parity gate and the XOR gate behave identically
+with two inputs; similarly, the even parity gate and the XNOR gate
+behave identically.
+But if there are more than two specified inputs, the XOR gate will emit
+1 only when there is exactly one 1 input, whereas the Odd Parity gate
+will emit 1 if there are an odd number of 1 inputs.
+The XNOR gate will emit 1 only when there is not exactly one 1
+input, while the Even Parity gate will emit 1 if there are an even
+number of 1 inputs. The XOR and XNOR gates include an attribute titled
+Multiple-Input Behavior that allow them to be configured to use the
+Odd Parity and Even Parity behavior.
+
+
If any of the
+inputs are the error value (e.g., if conflicting values are coming into
+the same wire) or floating, then the output will be the error value.
+
+
The multi-bit versions of each gate will perform its one-bit
+transformation bitwise on its inputs.
+
+
Note: Many authorities contend that the shaped XOR
+gate's behavior should correspond to the odd parity gate, but there is
+not agreement on this point. Logisim's default behavior for XOR gates is based
+on the IEEE 91 standard. It is also consistent with the intuitive
+meaning underlying the term exclusive or: A waiter asking
+whether you want a side dish of mashed potatoes, carrots, peas, or cole
+slaw will only accept one choice, not three, whatever some authorities
+may tell you. (I must admit, though, that I have not subjected this
+statement to a rigorous test.) You can configure the XOR and XNOR gates
+to use parity by changing its Multiple-Input Behavior attribute.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge (inputs, bit width according to Data Bits attribute)
+
The inputs into the component. There will be as many of these as
+specified in the Number of Inputs attribute.
+
+
Note that if you are using shaped gates, the west side of XOR and
+XNOR gates will be curved. Nonetheless, the input pins are in a line.
+Logisim will draw short stubs illustrating this; and if you overshoot a
+stub, it will silently assume that you did not mean to overshoot it. In
+"printer view", these stubs will not be drawn unless they are connected
+to wires.
+
+
East edge (output, bit width according to Data Bits attribute)
+
The gate's output, whose value is computed based on the current
+inputs as described above.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Number of Inputs attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its inputs).
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
+
+
Gate Size
+
Determines whether to draw a wider or narrower version of the
+component. This does not affect the number of inputs, which is specified
+by the Number of Inputs attribute; however, if the number of inputs exceeds 3 (for a
+narrow component) or 5 (for a wide component), then the gate will
+be drawn with "wings" to be able to accommodate the number of inputs
+requested.
+
+
Number of Inputs
+
Determines how many pins to have for the component on its west
+side.
+
+
Output Value
+
Indicates how false and true results should be translated into output values.
+By default, false is indicated by a low voltage (0) and true by a high voltage (1),
+but one or the other can be replaced by a high-impedance (floating) value
+instead. This allows wired-or and wired-and connections, as illustrated in
+the AND/OR/NAND/NOR Gate documentation.
+
+
Label
+
The text within the label associated with the gate.
+
+
Label Font
+
The font with which to render the label.
+
+
Multiple-Input Behavior (XOR and XNOR only)
+
When three or more inputs are provided, the XOR/XNOR gate's output will
+either be based on whether exactly one input is 1 (the default) or an odd number
+of inputs are 1.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the gate to be edited.
The HDL-IP library includes components that are meant to be described
+ entirely using hardware description languages. At the present time,
+ only one component is accessible, the VHDL entity.
+
A Logisim library holds a set of tools that allow you to
+ interact with a circuit via clicking and dragging the mouse in the
+ canvas area. Most often, a tool is intended for adding components of a
+ particular type into a circuit; but some of the most important tools,
+ such as the Poke Tool and the Select Tool, allow you to interact with
+ components in other ways.
+
All of the tools included in Logisim's built-in libraries are
+ documented in this reference material.
Displays the values of its eight one-bit inputs. Segments are either
+colored or light gray depending on the inputs. The correspondence is as
+follows.
+
+(Manufacturers vary as to how they map inputs to segments; the
+correspondence used here is based on Texas Instruments'
+TIL321.)
+
+
Pins
+
+
+
+
North edge, first from left (input, bit width 1)
+
Controls the middle horizontal segment.
+
+
North edge, second from left (input, bit width 1)
+
Controls the upper vertical segment on the left side.
+
+
North edge, third from left (input, bit width 1)
+
Controls the upper horizontal segment.
+
+
North edge, fourth from left (input, bit width 1)
+
Controls the upper vertical segment on the right side.
+
+
South edge, first from left (input, bit width 1)
+
Controls the lower vertical segment on the left side.
+
+
South edge, second from left (input, bit width 1)
+
Controls the bottom horizontal segment.
+
+
South edge, third from left (input, bit width 1)
+
Controls the lower vertical segment on the right side.
+
+
South edge, fourth from left (input, bit width 1)
+
Controls the decimal point.
+
+
+
+
Attributes
+
+
+
+
On Color
+
The color with which to draw the display segments and decimal point when
+they are on.
+
+
Off Color
+
The color with which to draw the display segments and decimal point when
+they are off.
+
+
Background
+
The color with which to draw the display's background (transparent by default).
+
+
Active On High?
+
If yes, then the segments light when the corresponding input is 1.
+If no, they light when the corresponding input is 0.
Displays a small grid of pixels, whose values are determined by the current
+inputs. The grid can have up to 32 rows and 32 columns.
+
+
Pins
+
+
The interface to the component varies depending on the value of the
+Input Format attribute. It has three possible values.
+
+
+
+
Columns
+
The inputs are lined along the component's south edge, with one
+multibit input for each column of the matrix. Each input has as many bits
+as there are rows in the matrix, with the low-order bit corresponding to the
+southmost pixel in the column. A 1 indicates to light the corresponding pixel,
+while a 0 indicates to keep the pixel dim. If any of the bits for a column are
+either floating or error values, then all pixels in the column are lit.
+
+
Rows
+
The inputs are lined along the component's west edge, with one multibit
+input for each row of the matrix. Each input has as many bits as there are
+columns in the matrix, with the low-order bit corresponding to the rightmost
+pixel in the row. As with the Columns format, a 1 indicates to light the
+corresponding pixel, and a 0 indicates to keep the pixel dim. If any bits for
+a row are floating or error values, then all pixels in the row are lit.
+
+
Select Rows/Columns
+
There are two inputs on the component's west edge. The upper multibit
+input has as many bits as there are columns in the matrix, with the low-order
+bit corresponding to the rightmost column. The lower multibit input has as
+many bits as there are rows in the matrix, with the low-order bit corresponding
+to the bottom row. If any bits in either input are floating or error
+values, all pixels in the matrix are lit. Normally, though, a pixel at a
+particular row-column location is lit if the corresponding column bit in the
+upper input is 1 and the corresponding row bit in the lower input is 1.
+For example, for a 5x7 matrix, if the first input is 01010 and the second is
+0111010, then the second and fourth columns are lit for the second, third,
+fourth, and sixth rows; the result appears to be a pair of exclamation points.
+(This input format may seem unintuitive, but LED matrixes are sold commercially
+with exactly this interface. Lite-On sells such components, for example.)
+
+
+
+
Attributes
+
+
+
+
Input Format (read-only after component is created)
+
Selects how the pins correspond to pixels, as outlined above.
+
+
Matrix Columns
+
Selects how many columns are in the matrix, which may range from 1 up to
+32.
+
+
Matrix Rows
+
Selects how many rows are in the matrix, which may range from 1 up to
+32.
+
+
On Color
+
Selects the color of a pixel when it is lit.
+
+
Off Color
+
Selects the color of a pixel when it is dim.
+
+
Light Persistence
+
When this is other than 0, a pixel that is lit remains lit
+for the given number of clock ticks after the component's inputs indicate
+that the pixel should become dim.
+
+
Dot Shape
+
The square option means that each pixel is drawn as a 10x10 square, filling
+the component with no gaps between pixels. The circle option means that each
+pixel is drawn as a diameter-8 circle, with gaps between each circle. The circle
+option is more difficult to interpret, but it more closely approximates the
+off-the-shelf LED matrix components.
Using a seven-segment display, shows the hexadecimal digit corresponding to
+the four-bit input. If any of the inputs are not 0/1 (either floating or error),
+then the display shows a dash ('-'). A separate one-bit input controls the
+display of the decimal point.
+
+
Pins
+
+
+
+
South edge, first from left (input, bit width 4)
+
This input is interpreted as an unsigned four-bit number, and the
+corresponding hexadecimal digit is displayed. If any of the bits are floating
+or error, then a dash ('-') is displayed.
+
+
South edge, second from left (input, bit width 1)
+
Controls the decimal point. If this is left unconnected, the decimal point
+remains off.
+
+
+
+
Attributes
+
+
+
+
On Color
+
The color with which to draw the display segments and decimal point when
+they are on.
+
+
Off Color
+
The color with which to draw the display segments and decimal point when
+they are off.
+
+
Background
+
The color with which to draw the display's background (transparent by default).
The user can drag the red knob within the rounded-square area, and the outputs
+update to indicate the knob's current x- and
+y-coordinates. This is meant to emulate the joysticks known from
+the days of classical arcade games.
+
+
Pins
+
+
+
+
West edge, north pin (output, bit width matches Bit Width attribute)
+
Indicates knob's x-coordinate, to be interpreted as an unsigned
+integer whose value will never be 0. Thus, a value of 1 represents the far left,
+and the maximum value for the bit width indicates the far right. When the knob
+is at rest (in the center), the value has the bit pattern 10...00.
+
+
West edge, south pin (output, bit width matches Bit Width attribute)
+
Indicates knob's y-coordinate, whose value ranges as with the
+x-coordinate pin. When the knob is pulled to the top, this output's
+value is 1, and when the knob is pulled to the bottom, the output is the
+maximum value for the bit width selected.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-2 through Alt-5 alter its Bit Width attribute.
+
+
+
+
Bit Width
+
The number of bits used to indicate each of the knob's coordinates.
+
+
Color
+
The knob's color as it is drawn on the screen.
+
+
+
+
Poke Tool Behavior
+
+
Pressing the mouse button while within the joystick area moves the knob to
+that location and updates the outputs. Dragging the mouse continues to move
+the knob and update the outputs, keeping the knob within the joystick's area.
+Releasing the mouse button reverts the knob back to its rest position.
This component allows the circuit to read keys typed from the keyboard -
+as long as the keys are representable in the 7-bit ASCII code.
+After clicking the component using the poke tool, the user can type characters,
+which accumulate in a buffer. At all times, the ASCII value for the leftmost
+character in the buffer is sent out the rightmost output. When the clock input
+is triggered, the leftmost character disappears from the buffer and the new
+leftmost character is sent on the rightmost output.
+
+
The supported characters for the buffer include all the printable ASCII
+characters, as well as space, newline, backspace, and control-L. In addition,
+the left-arrow and right-arrow keys move the cursor within the buffer, and the
+delete key deletes the character to the right of the cursor (if any).
+
+
The component is asynchronous in the sense that when the buffer is empty and
+the user types a character, that character is sent immediately as an output,
+without any wait for a clock pulse.
+
+
Pins
+
+
+
+
West edge, marked by a triangle (input, bit width 1)
+
Clock - when triggered while the read-enable pin isn't 0, the leftmost
+character from the buffer is deleted,
+and the outputs are updated to reflect the buffer's new status.
+
+
South edge, leftmost pin (input, bit width 1)
+
Read Enable - when 1 (or floating or error), a clock edge will consume
+the leftmost character from the buffer. The clock input is ignored when
+Read Enable is 0.
+
+
South edge, second pin from left (input, bit width 1)
+
Clear - when 1, the buffer is emptied and does not accept further
+characters.
+
+
South edge, second pin from right (output, bit width 1)
+
Available - this is 1 when the buffer contains at least one character
+and 0 when the buffer is empty.
+
+
South edge, rightmost pin (output, bit width 7)
+
Data - the 7-bit ASCII code for the leftmost character in the buffer,
+or 0 if the buffer is empty.
+
+
+
+
Attributes
+
+
+
+
Buffer Length
+
The number of characters that the buffer can hold at once.
+
+
Trigger
+
If the value is Rising Edge, then when the clock input changes
+from 0 to 1, the leftmost character is consumed (when enabled by the Read
+Enable input). If it is Falling Edge,, then this happens when the
+clock input changes from 1 to 0.
+
+
+
+
Poke Tool Behavior
+
+
Pressing the mouse button into the component gives keyboard focus to the
+component, and a vertical-bar cursor will be displayed.
+
+
Each character typed will then be inserted into the buffer, as long as the
+buffer hasn't reached its capacity and the character is one of those that the
+component supports: the printable characters within the 7-bit ASCII code, as
+well as space, backspace, newline, and control-L. Additionally, the user may
+type the left-arrow and right-arrow keys to change the location of the cursor
+within the buffer, and the user may type the delete key to delete the buffer
+character (if any) just to the right of the cursor.
Displays the value of its input by coloring the LED (as specified
+by its Color attribute) or not depending on whether the input is 1 or 0.
+
+
(The LED component is basically redundant with an output pin, except
+for a somewhat different appearance. Some users, though, thought it would
+be nice to include.)
+
+
Pins
+
+
A LED has only one pin, a 1-bit input which is used to determine whether
+to display the LED colored (when the input is 1) or darkened (when the input
+is anything else).
+
+
Attributes
+
+
When the component is selected or being added,
+the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The location of the input pin relative to the component.
+
+
Color
+
The color to display when the input value is 1.
+
+
Active On High?
+
If yes, then the LED is colored when the input is 1.
+If no, it is colored when the input is 0.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Location
+
The location of the label relative to the component.
+
+
Label Font
+
The font with which to render the label.
+
+
Label Color
+
The color with which to draw the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
This component implements a very simple dumb terminal. It receives a sequence
+of ASCII codes and displays each printable character. When the current row
+becomes full, the cursor moves to the following line, possibly scrolling all
+current rows up if the cursor was already in the bottom row. The only supported
+control sequences are: backspace (ASCII 8), which deletes the last character in
+the final row, unless the final row is already empty; newline (ASCII 10), which
+moves the cursor to the beginning of the following line, scrolling if necessary;
+and form-feed (ASCII 12, typed as control-L), which clears the screen.
+
+
Pins
+
+
+
+
West edge, upper pin (input, bit width 7)
+
Data - this is the ASCII value of the next character to be entered into
+the terminal.
+
+
West edge, lower pin marked by triangle (input, bit width 1)
+
Clock - when triggered while the write-enable pin isn't 0, the
+current ASCII value on the Data input is processed by the terminal.
+
+
South edge, leftmost pin (input, bit width 1)
+
Write Enable - when 1 (or floating or error), a clock edge will result
+in processing a new character from the data input. The clock and data inputs are
+ignored when Write Enable is 0.
+
+
South edge, second pin from left (input, bit width 1)
+
Clear - when 1, the terminal is cleared of all data, and all other inputs
+are ignored.
+
+
+
+
Attributes
+
+
+
+
Rows
+
The number of rows displayed in the terminal.
+
+
Columns
+
The maximum number of characters displayed in each row of terminal.
+
+
Trigger
+
If the value is Rising Edge, then when the clock input changes
+from 0 to 1, the data input is processed (when enabled by the write-enable
+and clear inputs).
+If it is Falling Edge,, then this happens when the
+clock input changes from 1 to 0.
+
+
Color
+
The color with which to draw the text appearing in the terminal.
+
+
Background
+
The color with which to draw the terminal's background.
The counter holds a single value, whose value is emitted on the output
+Q. Each time the clock input (diagrammed with a triangle on the
+component's south edge) triggers according to its Trigger attribute,
+the value in the counter may update based on
+the two inputs on the component's west edge: The upper input is called
+load and the lower is called count, and they are
+interpreted as follows.
+
+
+
load
count
trigger action
+
+
0 or z
0
+
The counter remains unchanged.
+
0 or z
1 or z
+
The counter increments.
+
1
0
+
The counter loads the value found at the
+ D input.
+
1
1 or z
+
The counter decrements.
+
+
+
The range of counting can be configured using the Maximum
+Value attribute. When the counter reaches this value, the next
+increment wraps the counter back to 0; and if it is at 0,
+then a decrement will wrap the counter around back to its maximum value.
+
+
In addition to the output Q, the component also includes a
+single-bit output carry. This is 1 whenever the counter is at its
+maximum and the load and count inputs indicate that the
+component should increment on the next step - or when the counter is at 0
+and the load and count inputs indicate to decrement at
+the next step.
+
+
The clear input resets the counter's value to 0 (all
+zeroes) asynchronously; that is, as long as the clr input
+is 1, the value is pinned to 0, regardless of the clock input.
+
+
Pins
+
+
+
+
East edge, labeled Q (output, bit width matches Data Bits attribute)
+
Outputs the value currently stored by the counter.
+
+
East edge, lower pin (output, bit width 1)
+
Carry: When load and count indicate to increment,
+this output is 1 whenever the counter is at its maximum. When load
+and count indicate to decrement, this output is 1 whenever the
+counter is at 0. At all other times, this output is 0.
+
+
West edge, top pin (input, bit width 1)
+
Load: When this is 1 while the count input is 0, the counter
+will load the value found at the data input at the next clock
+trigger - or, if the count input happens to be 1, the counter's
+value will decrement.
+
+
West edge, middle pin labeled D
+ (input, bit with matches Data Bits attribute)
+
Data: When the clock triggers while load is 1
+and count is 0, the counter's value changes to the value found at
+this input.
+
+
West edge, lower pin labeled ct (input, bit width 1)
+
Count: When this is 1 or unconnected, the value in the counter increments
+whenever the clock input is triggered - or it decrements if the load
+input happens to also be 1.
+
+
South edge, indicated with a triangle (input, bit width 1)
+
Clock: At the instant that this is triggered as specified by the Trigger
+attribute, the counter updates as indicated by the load and
+count inputs.
+
+
South edge, labeled 0 (input, bit width 1)
+
Clear: When 0 or undefined, this input has no effect.
+As long as it is 1, the counter's value is asynchronously pinned to 0. This
+occurs asynchronously - that is, without regard to the current clock input
+value. As long as this is 1, the other inputs have no effect.
+
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the value emitted by the component.
+
+
Maximum Value
+
The maximum value, at which point the counter will set its carry output.
+
+
Action On Overflow
+
The behavior when the counter attempts to increment beyond the maximum value
+or decrement beyond 0. Four possible actions are supported:
+
+
Wrap around
+
The next value is 0 (if incrementing - the maximum value if decrementing)
+
Stay at value
+
The counter's value remains at the maximum (or 0 if decrementing)
+
Continue counting
+
The counter continues incrementing/decrementing, keeping the number of bits
+as provided by the Data Bits attribute
+
Load next value
+
The next value is loaded from the D input.
+
+
+
Trigger
+
Configures how the clock input is interpreted. The value rising edge
+indicates that the counter should update its value at the instant when the
+clock rises from 0 to 1. The falling edge value indicates that it should
+update at the instant the clock falls from 1 to 0.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
Clicking the counter brings keyboard focus to the component
+(indicated by a red rectangle), and typing hexadecimal digits will
+change the value stored in the counter.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
Each flip-flop stores a single bit of data, which is emitted through
+the Q output on the east side. Normally, the value can be
+controlled via the inputs to the west side. In particular, the value
+changes when the clock input, marked by a triangle on
+each flip-flop, rises from 0 to 1 (or otherwise as configured); on this rising
+edge, the value changes according to the table below.
+
+
+
D Flip-Flop
+
T Flip-Flop
+
J-K Flip-Flop
+
S-R Flip-Flop
+
+
+
D
Q
+
0
0
+
1
1
+
+
+
+
T
Q
+
0
Q
+
1
Q'
+
+
+
+
J
K
Q
+
0
0
+
Q
+
0
1
+
0
+
1
0
+
1
+
1
1
+
Q'
+
+
+
+
S
R
Q
+
0
0
+
Q
+
0
1
+
0
+
1
0
+
1
+
1
1
+
??
+
+
+
+
Another way of describing the different behavior of the flip-flops
+is in English text.
+
+
+
D Flip-Flop: When the clock triggers, the
+value remembered by the flip-flop becomes the value of the D
+input (Data) at that instant.
+
+
T Flip-Flop: When the clock triggers, the
+value remembered by the flip-flop either toggles or remains the same
+depending on whether the T
+input (Toggle) is 1 or 0.
+
+
J-K Flip-Flop: When the clock triggers,
+the value remembered by the flip-flop
+toggles if the J and K inputs are both 1
+and the value remains the same if both are 0;
+if they are different, then the value becomes 1 if the J
+(Jump) input is 1 and 0 if the K (Kill)
+input is 1.
+
+
S-R Flip-Flop: When the clock triggers,
+the value remembered by the flip-flop
+remains unchanged if R and S are both 0,
+becomes 0 if the R input (Reset) is 1, and
+becomes 1 if the S input (Set) is 1.
+The behavior in unspecified if both inputs are 1.
+(In Logisim, the value in the flip-flop remains unchanged.)
+
+
+
+
By default, the clock triggers on a rising edge — that is, when the
+clock input changes from 0 to 1. However, the
+Trigger attribute allows this to change to a falling edge (when the clock
+input changes from 1 to 0), a high level (for the duration that the clock input
+is 1), or a low level (for the duration that the clock input is 0). The
+level-trigger options are unavailable for the T and J-K flip-flops, because
+a flip-flop behaves unpredictably when told to toggle for an indeterminate
+amount of time.
+
+
Pins
+
+
+
+
West edge, marked by triangle (input, bit width 1)
+
Clock input: At the instant that this input value switches from 0 to
+1 (the rising edge), the value will be updated according to the other
+inputs on the west edge. As long as this remains 0 or 1, the other
+inputs on the west edge have no effect.
+
+
West edge, other labeled pin(s) (input(s), bit width 1)
+
These inputs control how the flip-flop's value changes during the
+rising edge of the clock. Their exact behavior depends on the
+flip-flop; the above tables summarize their behavior.
+
+
East edge, labeled Q, north end (output, bit width 1)
+
Outputs the value currently stored by the flip-flop.
+
+
East edge, south end (output, bit width 1)
+
Outputs the complement of the value currently stored by the
+flip-flop.
+
+
South edge, east end (input, bit width 1)
+
Asynchronous reset: When 0 or undefined, this input has no effect.
+As long as it is 1, the flip-flop's value is pinned to 0. This occurs
+asynchronously - that is, without regard to the current clock input
+value. As long as this is 1, the other inputs have no effect.
+
+
South edge, center end (input, bit width 1)
+
Enable: When this is 0, clock triggers are ignored. The current bit
+continues to appear on the output. The clock triggers are enabled when this
+input is 1 or undefined.
+
+
South edge, west end (input, bit width 1)
+
Asynchronous set: When 1 or undefined, this input has no effect.
+When 1, the flip-flop's value is pinned to 1. This occurs asynchronously
+- that is, without regard to the current clock input value. As long as
+this input is 1, the other inputs have no effect, except for the
+asynchronous reset input, which has priority.
+
+
+
+
Attributes
+
+
+
+
Trigger
+
Configures how the clock input is interpreted. The value rising edge
+indicates that the flip-flop should update its value at the instant when the
+clock rises from 0 to 1. The falling edge value indicates that it should
+update at the instant the clock falls from 1 to 0. The high level value
+indicates that the flip-flop should update continuously whenever the clock
+input is 1. And the low level value indicates that it should update
+continuously when the clock input is 0. Note that the latter two options
+are unavailable for T and J-K flip-flops.
+
+
Label
+
The text within the label associated with the flip-flop.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
Clicking a flip-flop using the Poke Tool toggles the bit stored in
+the flip-flop, unless the asynchronous set/reset inputs currently
+pin the flip-flop's value.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
The RAM component, easily the most complex component in Logisim's
+built-in libraries, stores up to 16,777,216 values (specified in the Address
+Bit Width attribute), each of which can include up to to 32 bits
+(specified in the Data Bit Width attribute). The circuit can load and
+store values in RAM. Also, the user can modify individual values
+interactively via the Poke Tool, or the user can modify the entire
+contents via the Menu Tool.
+
+
Current values are displayed in the component. Addresses displayed
+are listed in gray to the left of the display area. Inside, each value
+is listed using hexadecimal. The value at the currently selected address
+will be displayed in inverse text (white on black).
+
+
The RAM component supports three different interfaces, depending on the
+Data Interface attribute.
+
+
+
+
One synchronous load/store port (default)
+
The component includes a single port on its east side that serves for both
+loading and storing data. Which it performs depends on the input labeled
+ld: 1 (or floating) indicates to load the data at the address
+designated on the component's west side, and 0 indicates to store the data
+given on the port. To transmit data into and out of the component, you will
+need to use a Controlled Buffer component, as illustrated below.
+
+
+
+
One asynchronous load/store port
+
This is the same as above, except that there is no clock. The value
+found on the data bus is stored into memory whenever the ld input is
+0. If, while the ld input is 0, the address or data changes, then an
+additional store occurs. This option is meant to more closely approximate the
+interface of many available random-access memories.
+
+
Separate load and store ports
+
Two data ports are provided - one on the west side for storing data,
+and another on the east side for loading data. This option removes the
+necessity of dealing with the Controlled Buffer and so it is easier to
+use.
+
+
Pins
+
+
+
+
A on west edge (input, bit width matches Address Bit Width attribute)
+
Selects which of the values in memory is currently being accessed by the
+circuit.
+
+
D on west edge (input, bit width matches Data Bit Width attribute)
+
This input is present only if "separate load and store ports" is selected
+for the Data Interface attribute. When a store is requested (via the clock changing
+from 0 to 1 while sel and str are both 1 or floating), the
+value found at this port is stored into memory at the currently selected address.
+
+
D on east edge (input/output or output, bit width matches Data Bit Width attribute)
+
If sel and ld are 1 or floating, then the RAM
+component emits the value found at the currently selected address on this port.
+If there is a single load/store port, the value read from this port is
+stored whenever a store is requested.
+
+
str on south edge (input, bit width 1)
+
Store: This input is present only if "separate load and store ports" is selected
+for the Data Interface attribute. When it is 1 or floating, a clock pulse will result
+in storing the data found on the west edge into memory (provided the
+sel input is also 1 or floating).
+
+
sel on south edge (input, bit width 1)
+
Chip select: This input enables or disables the entire RAM module, based on
+whether the value is 1/floating or 0. The input is meant primarily for
+situations where you have multiple RAM units, only one of which would be
+enabled at any time.
+
+
triangle on south edge (input, bit width 1)
+
Clock input: This is absent when the Data Interface attribute's value is "One
+asynchronous load/store port." In other circumstances, when ld is 0,
+and this input rises from 0 to 1 (and sel is 1/undefined and
+clr is 0), then the value at the currently selected address
+changes to whatever value is
+at the D pin. As long as the clock input remains 0 or 1,
+though, the D value will not be stored into memory.
+
+
ld on south edge (input, bit width 1)
+
Load: Selects whether the RAM should emit (on D)
+the value at the current address (A). This output behavior
+is enabled if out is 1 or undefined; if out
+is 0, then no value is pushed onto D - but if there is a combined
+load/store port, stores will be enabled.
+
+
clr on south edge (input, bit width 1)
+
Clear: When this is 1, all values
+in memory are pinned to 0, no matter what the other inputs are.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Address Bit Width attribute
+and Alt-0 through Alt-9 alter its Data Bit Width attribute.
+
+
+
+
Address Bit Width
+
The bit width of the address bits. The number of values stored in
+RAM is 2addrBitWidth.
+
+
Data Bit Width
+
The bit width of each individual value in memory.
+
+
Data Interface
+
Configures which of the three interfaces are used for communicating data
+into and out of the component.
This component iterates through a pseudorandom sequence of numbers, which
+steps forward to the following number in the sequence each time the clock is
+triggered while the component is enabled. Technically speaking, the algorithm
+used to compute the pseudorandom sequence is a linear
+congruential generator: Starting from a seed
+r0, the following number
+r1 is the number
+
+r1 =
+(25,214,903,917 r0 + 11)
+mod 248
+
+
The next value r2
+is computed from r1
+using the same computation, and so forth. This sequence is of 48-bit numbers;
+the value seen from the component is the low-order bits as configured
+by its Data Bits attribute, after first throwing out the lower 12 bits of
+the current seed.
+
+
Besides the clock input, the component also includes an enable
+input, which leads the clock input to be ignored when enable is 0,
+and the reset input, which resets the component's value asynchronously
+to the initial seed r0.
+
+
The initial seed is user-configurable. If it is configured at 0 (which is
+the default), then the seed is based on the current time; when instructed
+to reset through the reset input, the component computes a new
+seed based on the new current time.
+
+
Pins
+
+
+
+
East edge, labeled Q (output, bit width matches Data Bits attribute)
+
Outputs the value currently stored by the component.
+
+
West edge, top pin, labeled with a triangle (input, bit width 1)
+
Clock: At the instant that this is triggered as specified by the Trigger
+attribute, the component steps to the following number in its sequence.
+
+
West edge, bottom pin (input, bit width 1)
+
Enable: The component is enabled when this input is disconnected or 1;
+but if it is 0, then the clock input is ignored.
+
+
South edge (input, bit width 1)
+
Reset: When this is 1, the pseudorandom sequence asynchronously resets to
+the initial seed. (If seed is 0, this new seed should be different from the
+initial seed used previously.)
+
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the value emitted by the component.
+
+
Seed
+
The starting value used for the pseudorandom sequence. If this is 0
+(the default), then the starting value is based on the time that the random
+sequence began.
+
+
Trigger
+
Configures how the clock input is interpreted. The value rising edge
+indicates that the component should update its value at the instant when the
+clock rises from 0 to 1. The falling edge value indicates that it should
+update at the instant the clock falls from 1 to 0.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
A register stores a single multi-bit value, which is displayed in
+hexadecimal within its rectangle, and is emitted on its
+Q output. When the clock input
+(indicated by a triangle on the south edge) indicates so,
+the value stored in the register changes to the value of the
+D input at that instant. Exactly when the clock input indicates
+for this to happen is configured via the Trigger attribute.
+
+
The reset input resets the register's value to 0 (all
+zeroes) asynchronously; that is, as long as reset
+is 1, the value is pinned to 0, regardless of the clock input.
+
+
Pins
+
+
+
+
East edge, labeled Q (output, bit width matches Data Bits attribute)
+
Outputs the value currently stored by the register.
+
+
West edge, labeled D (input, bit width matches Data Bits attribute)
+
Data input: At the instant that the clock value rises from 0 to 1,
+the register's value changes to the value of the D input at
+that instant.
+
+
West edge, labeled en (input, bit width 1)
+
Enable: When this is 0, clock triggers are ignored. The current value
+continues to appear on the output. The clock triggers are enabled when this
+input is 1 or undefined.
+
+
South edge, indicated with a triangle (input, bit width 1)
+
Clock input: At the instant that this input value rises from 0 to
+1 (the rising edge), the register's value will be updated to the value
+of the D input.
+
+
South edge, labeled 0 (input, bit width 1)
+
Asynchronous reset: When 0 or undefined, this input has no effect.
+As long as it is 1, the register's value is pinned to 0. This occurs
+asynchronously - that is, without regard to the current clock input
+value. As long as this is 1, the other inputs have no effect.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the value stored in the register.
+
+
Trigger
+
Configures how the clock input is interpreted. The value rising edge
+indicates that the register should update its value at the instant when the
+clock rises from 0 to 1. The falling edge value indicates that it should
+update at the instant the clock falls from 1 to 0. The high level value
+indicates that the register should update continuously whenever the clock
+input is 1. And the low level value indicates that it should update
+continuously when the clock input is 0.
+
+
Label
+
The text within the label associated with the register.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
Clicking the register brings keyboard focus to the register
+(indicated by a red rectangle), and typing hexadecimal digits will
+change the value stored in the register.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
The ROM component stores up to 16,777,216 values (specified in the Address
+Bit Width attribute), each of which can include up to to 32 bits
+(specified in the Data Bit Width attribute). A circuit can access
+the current values in ROM, but it cannot change them. The user can modify individual values
+interactively via the Poke Tool, or the user can modify the entire
+contents via the Menu Tool.
+
+
Unlike the RAM component, the ROM component's current contents are
+stored as an attribute of the component. Thus, if a circuit containing
+a ROM component is used twice, then both ROM components will hold the
+same values. Also because of this behavior, the current ROM contents are
+stored in files created by Logisim.
+
+
Current values are displayed in the component. Addresses displayed
+are listed in gray to the left of the display area. Inside, each value
+is listed using hexadecimal. The value at the currently selected address
+will be displayed in inverse text (white on black).
+
+
Pins
+
+
+
+
A on west edge (input, bit width matches Address Bit Width attribute)
+
Selects which of the values are currently being accessed by the
+circuit.
+
+
D on east edge (input/output, bit width matches Data Bit Width attribute)
+
Outputs the value at the currently selected address at the
+D pin if sel is 1 or floating. If sel
+is 0, then D will be floating.
+
+
sel on south edge (input, bit width 1)
+
If you have just one ROM module, ignore this input.
+If you have multiple ROM modules in parallel, you can use this input
+to enable or disable the entire ROM module, based on whether the value is
+1 or 0. In other words, when this is 0, no value is emitted on
+the D output.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Address Bit Width attribute
+and Alt-0 through Alt-9 alter its Data Bit Width attribute.
+
+
+
+
Address Bit Width
+
The bit width of the address bits. The number of values stored in
+ROM is 2addrBitWidth.
This register consists of several stages, where each clock may lead to
+each stage receiving the value in the previous stage, while a new value is
+loaded into the first stage. The component optionally also supports parallel
+loads and stores to all stages' values.
+
+
The clear input resets all stages to 0 (all
+zeroes) asynchronously; that is, as long as the clear input
+is 1, all values are pinned to 0, regardless of the clock input.
+
+
Pins
+
+
* An asterisk marks pins that exist only when the Parallel Load attribute
+is enabled.
+
+
+
+
West edge, top pin (input, bit width 1)
+
Shift: When 1 or disconnected, all stages advance with the clock trigger;
+but if it is 0, no advance takes place. This input is ignored if the Load
+input is 1.
+
+
West edge, middle pin (input, bit width matches Data Bits attribute)
+
Data: When advancing the stages, the value found at this input is loaded
+into the first stage.
+
+
West edge, bottom pin marked with triangle (input, bit width 1)
+
Clock: At the instant that this is triggered as specified by the
+Trigger attribute, the component may advance the stages or load new values.
+
+
*North edge, left pin (input, bit width 1)
+
Load: When this 1, the values found on the other north-edge pins are
+loaded into all stages at the next clock trigger. When 0 or disconnected, no
+load occurs.
+
+
*North edge, other pins (input, bit width matches Data Bits attribute)
+
Data: These values are loaded into all stages when the clock is triggered
+while the load input is 1. The leftmost input corresponds to the
+youngest stage.
+
+
South edge, left pin (input, bit width 1)
+
Clear: When this is 1, all stages are asynchronously reset to 0, and all
+other inputs are ignored.
+
+
*South edge, other pins (output, bit width matches Data Bits attribute)
+
Output: Emits the value stored in each stage, with the youngest stage
+reflected on the leftmost of the pins (next to the clear input).
+
+
East edge (output, bit width matches Data Bits attribute)
+
Output: Emits the value stored in the final (oldest) stage.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Number of Stages attribute
+and Alt-0 through Alt-9 alter its Data Bits attribute.
+
+
+
+
Data Bits
+
The bit width of the value stored in each stage.
+
+
Number of Stages
+
The number of stages included in the component.
+
+
Parallel Load
+
If yes, then the component includes inputs and outputs facilitating
+parallel access to all the stages' values.
+
+
Trigger
+
Configures how the clock input is interpreted. The value rising edge
+indicates that the register should update its value at the instant when the
+clock rises from 0 to 1. The falling edge value indicates that it should
+update at the instant the clock falls from 1 to 0.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
If the Parallel Load attribute is no, or if the Data Bits attribute is more
+than 4, then poking the register has no effect. Otherwise, clicking the
+component will bring keyboard focus to the clicked stage
+(indicated by a red rectangle), and typing a hexadecimal digit will
+change the value stored in that stage.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
Emits 1 on exactly one output; which output is 1 depends on the
+current value received through the input on the south edge.
+
+
Pins (assuming component faces east, select is bottom/left)
+
+
+
+
East edge, variable number (outputs, bit width 1)
+
The outputs are numbered starting with 0 on the north. Each output
+will be 1 if its number matches the value currently received through the
+select input on the south; otherwise, its value will be either zero or
+floating, depending on the value of the Three-State? attribute.
+If the select input contains any unspecified bits, then all outputs are
+floating.
+
+
South edge, left side (input, bit width 1)
+
Enable: When 0, all outputs consist of all floating bits (or zeros),
+regardless of the select input.
+
+
South edge, right side indicated by gray circle (input, bit width matches Select Bits attribute)
+
Select input: The value of this input determines which of the
+outputs is 1.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '1' through '4' alter its Select Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (specifying which side has the outputs).
+
+
Select Location
+
The location of the select and enable lines relative to the component.
+
+
Select Bits
+
The bit width of the component's select input on its south edge.
+The number of outputs for the decoder will be
+2selectBits.
+
+
Three-state?
+
Specifies whether the unselected outputs should be floating (Yes) or
+zero (No).
+
+
Disabled Output
+
Specifies what each bit of the outputs should be when the component is
+disabled (i.e., when the enable pin is 0). Options include zero and floating;
+in the latter case, the outputs are effectively disconnected from any other ports.
+
+
Include Enable?
+
The component has an enable input when this attribute is yes.
+The attribute is primarily for supporting circuits built using older versions of
+Logisim that did not provide an enable input.
Copies the input on the west edge onto exactly one of the outputs on
+the east edge; which of these outputs is specified via the
+current value received through the input on the south edge.
+I find it useful to think of a demultiplexer as analogous to a railroad
+switch, controlled by the select input.
+
+
(Incidentally, some authorities spell this
+demultiplexor,
+but demultiplexer is the predominant
+spelling.)
+
+
Pins (assuming component faces east, select is bottom/left)
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The value to be routed to one of the outputs on the east edge.
+
+
East edge, variable number (outputs, bit width matches Data Bits
+attribute)
+
The outputs are numbered starting with 0 on the north. An output
+will match the west input if its number matches the value currently
+received through the select input on the south; otherwise, its value
+will be either all-zeroes or all-floating, depending on the value of
+the Three-State? attribute.
+If the select input contains any unspecified bits, then all outputs are
+floating.
+
+
South edge, left side (input, bit width 1)
+
Enable: When 0, all outputs consist of all floating bits,
+regardless of the data and select inputs.
+
+
South edge, right side indicated by gray circle (input, bit width matches Select Bits attribute)
+
Select input: The value of this input determines to which output on
+the east edge to route the value received on the west edge.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '1' through '4' alter its Select Bits attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (specifying which side has the outputs).
+
+
Select Location
+
The location of the select and enable lines relative to the component.
+
+
Select Bits
+
The bit width of the component's select input on its south edge.
+The number of outputs for the demultiplexer will be
+2selectBits.
+
+
Data Bits
+
The bit width of the data being routed through the demultiplexer.
+
+
Three-state?
+
Specifies whether the unselected outputs should be floating (Yes) or
+zero (No).
+
+
Disabled Output
+
Specifies what each bit of the outputs should be when the component is
+disabled (i.e., when the enable pin is 0). Options include zero and floating;
+in the latter case, the outputs are effectively disconnected from any other ports.
+
+
Include Enable?
+
The component has an enable input when this attribute is yes.
+The attribute is primarily for supporting circuits built using older versions of
+Logisim that did not provide an enable input.
The Plexers library includes control components.
+Like the components of the Gates library, all are combinational,
+but their purpose is generally for routing values.
Copies an input on the west edge onto the output on
+the east edge; which of the inputs to copy is specified via the
+current value received through the input on the south edge.
+I find it useful to think of a multiplexer as analogous to a railroad
+switch, controlled by the select input.
+
+
(Incidentally, some authorities spell this
+multiplexor,
+but multiplexer is the predominant
+spelling.)
+
+
Pins (assuming component faces east, select is bottom/left)
+
+
+
+
West edge, variable number (inputs, bit width matches Data Bits attribute)
+
Data values, one of which is to be routed to the output.
+Each input data value is numbered, starting with 0 on the north.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The output value will match the input values on the west
+edge whose number is the same as the value currently received
+through the select input on the south.
+If the select input contains any unspecified (i.e., floating) bits,
+then the output is completely floating.
+
+
South edge, left side indicated by gray circle (input, bit width matches Select Bits attribute)
+
Select input: The value of this input determines which input
+on the west edge to route to the output on the east edge.
+
+
South edge, right side (input, bit width 1)
+
Enable: When 0, the multiplexer's output consists of all floating bits,
+regardless of the data and select inputs.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '1' through '4' alter its Select Bits attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Select Location
+
The location of the select and enable lines relative to the component.
+
+
Select Bits
+
The bit width of the component's select input on its south edge.
+The number of inputs to the multiplexer will be
+2selectBits.
+
+
Data Bits
+
The bit width of the data being routed through the multiplexer.
+
+
Disabled Output
+
Specifies what each bit of the output should be when the component is
+disabled (i.e., when the enable pin is 0). Options include zero and floating;
+in the latter case, the output is effectively disconnected from any other ports.
+
+
Include Enable?
+
The component has an enable input when this attribute is yes.
+The attribute is primarily for supporting circuits built using older versions of
+Logisim that did not provide an enable input.
The component has a number of inputs on its west edge, with the first
+labeled 0 and the other numbered from there. The component determines
+the indices of the inputs whose values are 1, and it emits the highest index.
+For example, if inputs 0, 2, 5, and 6 are all 1, then the priority encoder
+emits a value of 110. If no inputs are 1, or if the component is
+disabled, then the output of the priority encoder is floating.
+
+
The priority encoder is designed so that a number of encoders can be
+daisy-chained to accommodate additional inputs. In particular, the component
+includes an enable input and an enable output. Whenever the enable input is 0,
+the component is disabled, and the output will be all floating bits. The enable
+output is 1 whenever the component is enabled and none of the indexed inputs are
+1. Thus, you can take two priority encoders and connect the enable output
+of the first to the enable input of the second: If any of the indexed inputs
+to the first are 1, then the second will be disabled and so its output will be
+all floating. But if none of the first's indexed inputs are 1, then its output
+will be all-floating bits, and the second
+priority encoder will be enabled and it will identify the highest-priority
+input with a 1.
+
+
An additional output of the priority encoder is 1 whenever the priority
+encoder is enabled and finds a 1 on one of the indexed inputs. When
+chaining priority encoders together, this output can be used to identify
+which of the encoders was triggered.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge, variable number (inputs, bit width 1)
+
Input values, indexed from 0 at the top/west end of the edge.
+
+
East edge, upper pin (output, bit width matches Select Bits attribute)
+
Output: the highest index among those inputs whose value is 1 - or all
+floating bits if no inputs are 1 or if the component is disabled via the
+Enable In input.
+
+
East edge, lower pin (output, bit width 1)
+
Group Signal: 1 if the component is enabled and at least one indexed input
+has a value of 1; otherwise this output is 0.
+
+
South edge (input, bit width 1)
+
Enable In: if 0, the component is disabled; otherwise the component is
+enabled.
+
+
North edge (output, bit width 1)
+
Enable Out: 1 if this component is enabled and none of the indexed inputs
+are 1; otherwise the output is 0.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '1' through '4' alter its Select Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Select Bits
+
The bit width of the component's primary output.
+The number of indexed inputs to the priority encoder will be
+2selectBits.
+
+
Disabled Output
+
Specifies what each bit of the output should be when the component is
+disabled (i.e., when the enable pin is 0). Options include zero and floating;
+in the latter case, the output is effectively disconnected from any other ports.
Given an input of several bits, this will divide it into several
+equal-sized groups (starting from the lowest-order bit) and output
+the group selected by the select input.
+
+
For example, if we have an eight-bit input 01010101, and we are to have
+a three-bit output, then group 0 will be the lowest-order three bits 101,
+group 1 will be the next three bits, 010, and group 2 will be the next three
+bits 001. (Any bits beyond the top are filled in with 0.) The select
+input will be a two-bit number that selects which of these three groups
+to output; if the select input is 3, then 000 will be the output.
+
+
Pins (assuming component faces east)
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
Data value from which bits should be selected for the output.
+
+
East edge (output, bit width matches Output Bits attribute)
+
A group of bits from the data value, as selected by the select
+input.
+
+
South edge (input, bit width is quotient of Data Bits and Output Bits, rounded up)
+
Select input: Determines which of the bit groups should be routed
+to the output.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Output Bits attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
The build in assembler of logisim-evolution supports besides the
+ instructions provided by the used processor several features as described
+ in this help page.The assembler uses syntax highlighting and error
+ detection. Furthermore it translates the instructions into byte-code that
+ can be executed by the processor. Although the structure of the assembler
+ would allow to write out an elf-file this feature is not yet implemented.
+
Using the GUI
+
When opening the assembler you are presented with a new window as shown
+ below:
+
+
+
The GUI consists of three components:
+
+
The tool bar which is on top of the editing area.
+
The line indication bar with error indicators to the left of the
+ editing area.
+
The editing area.
+
+
The toolbar
+
The toolbar provides the main functions of the assembler by use of
+ several icons:
+
+ This icon activates the loading of an assembly file into the editing area.
+ The load function can also be activated by the keyboard shortcut (Ctrl-L).
+
+ This icon activates the saving of the current contents in the editing
+ area. The save function can also be activated by the keyboard shortcut
+ (Ctrl-S).
+
+ This icon activates the save-as function of the current contents in the
+ editing area. The save-as function has no keyboard shortcut.
+
This icon activates the
+ assemble function of the current contents in the editing area. The
+ assemble function cal also be activated by the keyboard shortcut (ALT-A).
+
This icon jumps to an error detected
+ before the current cursor position. This function is also available by the
+ keyboard shortcut (Ctrl-P).
+
This icon jumps to an error detected after
+ the current cursor position. This function is also available by the
+ keyboard shortcut (Ctrl-N).
+
+ This icon activated the assemble function and, when no errors are
+ detected, loads the program into memory. The run function can also be
+ activated by the keyboard shortcut (ALT-R).
+
+ This icon show this help screen.
+
To the right of the toolbar the current line of the cursor and the total
+ number of lines in the editing area are displayed. In case this indicator
+ lights up yellow there are changes detected in the editing area.
+
The line indicator bar
+
The line indicator bar hold, besides the current line number, also the
+ error indicator icons. Hovering over the error indicator bar will show
+ (one of) the error(s) detected on the given line in the editing area.
+
The editing area
+
The editing area contains all the code you might want to use. In case
+ your code contains errors (after activating the assemble or run function)
+ the errors will be displayed by an error icon in the line indicator bar
+ and a small red line underneath the text causing the problem. hovering
+ over this text with the mouse will display the error cause. It is
+ important to note that, when multiple errors are present in one line, only
+ one will be displayed by the error marker in the line indicator bar.
+ Furthermore, in case of calculations (like in line 17 in the above showed
+ image) it might be that only the 8 is marked instead of the complete
+ calculation.
+
Using calculations
+
The assembler supports two types of calculations:
+
+
Program counter (PC) relative calculations
+
Absolute calculations
+
+
Program counter relative calculations
+
In case an address is required relative to the current program counter
+ these calculations can be performed by using the reserved register pc.
+ Also the usage of labels and constants are allowed in these calculations.
+
Examples: pc+8 , pc-0x40, mylabel-pc, etc.
+
Absolute calculations
+
In absolute calculations a constant value is calculated. To perform
+ absolute calculations labels and constants are allowed.
+
Calculation types
+
Following calculation types are supported:
+
+
+ => Addition
+
- => Subtraction
+
* => Multiplication
+
/ => Integer division
+
% => Integer remainder
+
<< => Shift left
+
>> => Shift right
+
+ Note: Currently the parentheses are not supported.
+
Calculation order
+
Important: For the moment the calculations are performed
+ left-to-right independent of the hierarchy of the operator!
+
This means:
+
5+10*2 is calculated as (5+10)*2 = 30
+
10*2+5 is calculated as (10*2)+5 = 25
+
It is on the todo list to improve this poor calculation support.
+
Using macros
+
The build in assembler supports macros. The syntax for a macro is:
+
.macro<name><nr_of_variables>
+
<BODY>
+
.endm
+
A macro definition needs two parameters:
+
+
<name> This parameter is the name of the macro to be
+ used in the rest of your program.
+
<nr_of_variables> This parameter specifies the number
+ of variables that are used inside the macro. This parameter should be a
+ positive integer value (e.g. 0,1,2,....)
+
+
Allowed constructs inside a macro
+
Inside a macro you can use only instructions, labels, calculations, and
+ calls to other macros. It is important to note that labels defined inside
+ the <BODY> of a macro are local to the macro and cannot be
+ referenced outside the macro.
+
Using variables inside a macro
+
If the parameter <nr_of_variables> is a number bigger
+ than 0, the macro must be called with this number of values. Each of this
+ values can be referenced inside a macro with the indicator @<x>
+ where <x> is a number. Hence @1 references parameter 1, @2
+ parameter 2, etc.
+
Using macro calls inside a macro
+
Macros allow to call other macros, however there are two restrictions:
+
+
A macro cannot call itself; recursive macros are not supported.
+
Two macros cannot call each other; circular calls are not supported.
+
+
Assembler directives
+
There are several directives supported as described below.
+
Labels
+
Labels can be used by the syntax <name>:
+ The <name> must start with a letter and may contain
+ letters (a..z;A..Z), numbers (0..9), and underscores (_). Note that labels
+ specified inside a macro are local to the macro. All other labels are
+ global (hence a global label can be referenced inside a macro).
+
Named constants
+
Named constants can be defined by the syntax .equ<name>
+ <value>. The <name> parameter must start
+ with a letter and may contain letters (a..z;A..Z), numbers (0..9), and
+ underscores (_). The <value> field can contain a number or
+ a calculation.
+
Sections
+
You can divide your program into sections by using .section
+ <name>. The <name> parameter must start
+ with a letter and may contain letters (a..z;A..Z), numbers (0..9), and
+ underscores (_). There are four predefined section names being .text,
+ .data, .rodata, .bss.
+ These do not require the .section keyword in front of
+ them.
+
Remarks
+
Remarks are supported by placing a # in front of them
+ and extend until the end of the line. Multi line remarks can be realized
+ by putting in front of each line the #.
+
Strings
+
Strings can be specified by .string "<str>",
+ .ascii"<str>", or .asciz"<str>".
+ The <str> can contain any contents and may be multiple
+ lines. Following escape codes can be used:
+
+
\n -> insert a new-line character.
+
\" -> insert a double quote.
+
\t -> insert a tab-character.
+
\r -> insert a carriage return character.
+
\f -> insert a form feed.
+
\\ -> insert a back slash.
+
+
Both .string and .asciz will
+ automatically insert a zero character at the end of the string.
+
Memory addresses
+
By default the assembler will start at memory address 0x00000000. To be
+ able to change the current memory address the directive .org
+ <address> can be used, where the <address>
+ is a value within a 32-bit address space. Note: only
+ inter-section overlap will be checked by the assembler. If inside a
+ section an address is specified that is already being occupied, the values
+ are overwritten.
+
Constants
+
There are several ways to fill the memory with constant values. Besides
+ from the byte-based way, all the others use a little-endian storage
+ method, meaning that the least significant byte is stored at the lowest
+ memory address, and the most significant byte at the highest memory
+ address. The supported directives are:
+
+
.byte<value1>[,<value2>,...]
+ This directive stores the value(s) interpreted as bytes one after the
+ other into memory.
+
.half <value1>[,<value2>,...]
+ .2byte<value1>[,<value2>,...]
+ .short<value1>[,<value2>,...]
+ These directives store the value(s) interpreted as 16-bit values
+ one after the other into memory.
+
.word <value1>[,<value2>,...]
+ .4byte<value1>[,<value2>,...]
+ .long<value1>[,<value2>,...]
+ These directives store the value(s) interpreted as 32-bit values one
+ after the other into memory.
+
.dword<value1>[,<value2>,...]
+ .8byte<value1>[,<value2>,...]
+ .quad<value1>[,<value2>,...]
+ These directives store the value(s) interpreted as 64-bit values one
+ after the other into memory.
The disassembler takes the program stored in memory and transforms it to
+ a human readable contents. If available the disassembler uses the elf
+ section headers to extract defined labels and sections. Otherwise it uses
+ directly the information stored in memory to decode the information. The
+ disassembler has some features that are described below.
+
Automatic label detection
+
Where possible the disassembler tries to automatically detect labels in
+ your program. The detected labels will be called logisim_label_<x>
+ where <x> is a number starting with 1. The
+ labels are ordered from top to bottom, such that searching for a label is
+ facilitated.
+
Automatic program counter and opcode insertion
+
After each line where an instruction is detected the disassembler will
+ insert a remark containing the program counter (pc) value and the
+ instruction's binary opcode.
+
Break point support
+
The disassembler supports breakpoints. Breakpoints can be set/cleared by
+ either clicking in the left vertical bar next to the instruction, or by
+ selecting a line and pressing the b or clicking on
+ either the button Add break point or Remove break point.
+
The moment the cpu reaches a break point it will stop executing and the simulation state controller will indicate
+ a break point reached. The instruction next to the break point will not be
+ executed. Finally upon reaching a break point the disassembler will
+ automatically jump to the line at which the break point is encountered.
+
+
+
diff --git a/src/main/resources/doc/en/html/libs/soc/index.html b/src/main/resources/doc/en/html/libs/soc/index.html
new file mode 100644
index 0000000000..fe9f3fa463
--- /dev/null
+++ b/src/main/resources/doc/en/html/libs/soc/index.html
@@ -0,0 +1,61 @@
+
+
+
+
+ index
+
+
+
System On Chip components library
+
The system on chip components library contain all components required to
+ perform a functional simulation of a system on chip.
To be able to perform a System On Chip (SOC) simulation you require to
+ have in your sheet at least:
+
+
One of the processors marked with the -icon.
+
One bus marked with the -icon.
+
One memory simulator marked with the -icon.
+
+
Furthermore, both the memory simulator and the processor need to be
+ connected to the bus. This can be achieved by defining the Connected
+ bus attribute of the respective components.
+
Restrictions
+
A SOC system can only be local on one sheet, meaning that a given bus
+ component is only visible on the sheet it is placed. Building hierarchical
+ systems is only possible when having the base system on one sheet and the
+ extensions, for example VHDL-extentions or circuits, connected through the
+ base system by means of input- and output pins.
+
Simulation speed
+
One has to realize that this library is intended to visualize what is
+ going on in a SOC. Hence it provides in no way the means to perform (near)
+ real-time simulations of your SOC. For this purpose more adequate systems
+ are for example QEMU.
+
+
On the test system with all parts of the system visible a maximum of 3 Hz
+ tick-frequency was measured. Disabling some of the details for faster
+ simulation improved the speed to 8 Hz. The best simulation speed can be
+ achieved to use super-circuits with dynamic elements. Here the simulation
+ speed went up to approx. 3kHz.
The nios2 simulator is a complete ISA-simulator of Intel's nios2 soft
+ core (except for the f-version). It can be used to show the execution of a
+ program on an embedded system. Note that although the simulator executes
+ one instruction per clock cycle, it is not a cycle accurate simulation as
+ aspects like cache-stalls, data-dependency stalls, bus wait cycles, etc.
+ are not taken into account in the simulation. It provides a functional
+ simulation for showing SOC-design where the hardware is not yet available.
+
Pins
+
On the north side of the Nios2 simulation component you will find the
+ custom-instruction interface signals where you can add your
+ custom-instruction hardware/accelerators to be used in your simulations.
+ Please refer to Intel's documentation on custom instructions with the
+ nios2 on how to use them.
+
On the west side of the Nios2 simulation components following inputs are
+ present:
+
+
Reset: This the reset input of the Nios2
+ simulation component that will reset asynchronously the Nios2 when at
+ '1' and let the cpu run when at '0'.
+
Clock: This is the clock input of the Nios2
+ simulator component. Each time a positive edge is seen on this input a
+ new instruction will be fetched and executed.
+
IRQ[0..31]: The Nios2 simulator provides up
+ to 32 IRQ inputs (defined by the below described attribute IRQs). Each
+ of these IRQ-inputs is active high. Please refer to Intel's
+ documentation on IRQ-behavior on how to provide proper signals to these
+ inputs.
+
+
Attributes
+
The Nios2 simulation component provides following attributes:
+
+
Reset vector:This attribute
+ specifies the memory address of the first instruction to be executed
+ when the Reset pin is activated. In general the value specified here
+ should be the address of the entry point of your program. Note that all
+ addresses are 32-bit values.
+
Exception vector: Upon detection of an IRQ
+ (see IRQ-pins above), or an software exception instruction, the Nios2
+ simulator will start executing the program starting from this address.
+ In general the value specified here should be the address of the
+ exception handling routine in your program.
+
Break vector: This attribute specifies the
+ memory address of the break service routine which is executed upon
+ detection of a break instruction.
+
Number of IRQ lines: This attribute
+ specifies how many external IRQ-pins are available. It's value can be
+ within 0 (no IRQ lines) and 32 (maximum number of IRQ lines).
+
State visible:When disabling the state by
+ specifying No for this attribute the simulation speed can be improved
+ (see the remark on simulation speed in the library
+ description).
+
Label: Here the label of the components can
+ be specified. Note that the label is used in many places to reference to
+ this component. In case the label is not defined the components will be
+ referenced as "Nios2s simulator @x,y" where x and y
+ are the absolute coordinates of the anchor of this component inside the
+ sheet.
+
Label font: With this attribute the font of
+ the label can be specified.
+
Label visible: With this attribute you can
+ specify if the label is visible or not.
+
Connected Bus: This attribute let's you
+ connect the Nios2 simulator to a bus component.
+ For a successful simulation you have to connect your Nios2 simulator to
+ such a component.
+
+
Visible components
+
The Nios2 simulator has several state components that are visible when
+ the State visible attribute is set to True.
+ Most of these components can also be visualized in a separate window when
+ the component is hidden in a sub-circuit (see super-component menu below).
+ The different components are:
+
+
The register file. The Nios2 processor contains 32 general purpose
+ registers (r0..r31). The current values of these registers are shown on
+ the left-top square marked by Register file.
+ When a register value is shown by a sequence of question marks, it means
+ that the value is unknown (normal start-up behavior of the processor).
+ Each time a value is written to a register it will be highlighted in
+ blue and the new value will be shown.
+
The program counter. The program counter (PC) hold the current address
+ from which the next instruction will be fetched.
+
The status register. The status register (status) hold the current
+ state of the Nios2 processor. For information on the status register
+ please refer to Intel's documentation on the nios2 processor.
+
The exception status register. The exception status register (estatus)
+ holds a copy of the status register when entering an exception. For
+ information on the estatus register please refer to Intel's
+ documentation on the nios2 processor.
+
The break status register. The break status register (bstatus) holds a
+ copy of the status register when a break instruction is executed. For
+ information on the bstatus register please refer to Intel's
+ documentation on the nios2 processor.
+
The execution trace window. The execution trace window shows the last
+ 21 instructions executed by the nios2 processor. The last instruction
+ executed is shown on the top. The tace window provides three parts of
+ information, namely:
+
+
The program counter value where the instruction was fetched.
+
The binary opcode of the fetched instruction.
+
The assembly mnemonic of the fetched instruction in case the
+ fetched instruction has a correct binary opcode.
+
+ This component will be updated at each instruction fetch.
+
The IRQ-status, irq-mask, and irq-pending display. In case at least
+ one IRQ-input is selected by the Number of IRQ lines attribute,
+ this component will be shown. For each of the IRQ-pins a square on the
+ top of the component will indicate the current state of the IRQ-line.
+ The square below will indicate the corresponding bit in the IRQ-mask
+ register. Finally the square on the bottom will indicate if an unmasked
+ IRQ is pending. Note: this component does not show the state
+ of the global IRQ-enable bit which is present in the status register.
+
The connected bus indicator. To the bottom left of the component
+ (shown above in red) is the indicator to which bus
+ component the nios2 is connected. In case the nios2 is connected
+ to a bus component, this indicator will turn
+ green and shows the label of the connected bus. This bus indicator is
+ not available in the separate window view and will not be hidden by the
+ State visible attribute.
+
The simulation control component. To the right of the connected bus
+ indicator you can find the simulation control component. This component
+ is described in more details here, and
+ is available as dynamic element.
Clicking with the right mouse button on the symbol of the Nios2 simulator
+ will pop-up a menu. This menu is extended with three new menu items,
+ namely:
+
+
Open assembler. Selecting this menu item
+ will open the assembler. The assembler
+ provides the possibility to write your own assembly programs and run
+ them on the Nios2.
+
Read elf file. Selecting this menu item will
+ open a file selection window in which you can read in an elf-file
+ (executable) generated for a Nios2 processor by for example a gcc-cross
+ compile tool chain. The executable contents of the elf-file will be
+ loaded into memory, the reset vector of the Nios2 will be set to the
+ entry-point of the loaded program, and the Nios2 simulator will be
+ initialized to reset state. Note that loading an elf program will not
+ modify the value of the Reset vector
+ attribute.
+
Show loaded program. This menu option is
+ only present if an executable program has been loaded into memory,
+ either by the assembler, or by reading an elf file. When selecting this
+ menu item the disassembler will be
+ shown.
+
+
Super circuit menu items
+
When the Nios2 simulator is located in a sub-circuit, it will add four
+ menu items to the menu of this sub-circuit, namely:
+
+
<name>: Open assembler. Selecting this
+ menu item will open the assembler. The
+ assembler provides the possibility to write your own assembly programs
+ and run them on the Nios2.
+
<name>: Read elf file. Selecting this
+ menu item will open a file selection window in which you can read in an
+ elf-file (executable) generated for a Nios2 processor by for example a
+ gcc-cross compile tool chain. The executable contents of the elf-file
+ will be loaded into memory, the reset vector of the Nios2 will be set to
+ the entry-point of the loaded program, and the Nios2 simulator will be
+ initialized to reset state. Note that loading an elf program will not
+ modify the value of the Reset vector
+ attribute.
+
<name>: Show CPU State. This menu item
+ will open a new window showing the visible component 1 through 7 as
+ described in the Visible components section.
+
<name>: Show loaded program. This menu
+ option is only present if an executable program has been loaded into
+ memory, either by the assembler, or by reading an elf file. When
+ selecting this menu item the disassembler
+ will be shown.
+
+
In the above menu items <name> is the
+ label of the Nios2 simulator (see the Label
+ attribute above). If no label name is given <name>
+ is given by Nios2@x,y where x and y
+ are the coordinates of the anchor position of the Nios2 Simulator in the
+ sub-circuit.
+
Supported instructions
+
+
+
+
Arithmetic and logical instructions
+
+
+
and
+
or
+
xor
+
nor
+
sub
+
mul
+
+
+
div
+
divu
+
mulxss
+
mulxuu
+
mulxsu
+
andi
+
+
+
ori
+
xori
+
andhi
+
orhi
+
xorhi
+
addi
+
+
+
subi
+
muli
+
nop
+
mov
+
movhi
+
movi
+
+
+
movui
+
movia
+
+
+
+
+
Comparison instructions
+
+
+
cmpeq
+
cmpne
+
cmpge
+
cmpgeu
+
cmplt
+
cmpltu
+
+
+
cmpgt
+
cmpgtu
+
cmple
+
cmpleu
+
cmpeqi
+
cmpnei
+
+
+
cmpgei
+
cmpgeui
+
cmplti
+
cmpltui
+
cmpgti
+
cmpgtui
+
+
+
cmplei
+
cmpleui
+
+
+
+
+
Custom instructions
+
+
+
custom
+
+
+
+
+
Data transfer instructions
+
+
+
ldw
+
ldh
+
ldhu
+
ldb
+
ldbu
+
ldwio
+
+
+
ldhio
+
ldhuio
+
ldbio
+
ldbuio
+
stw
+
sth
+
+
+
stb
+
stwio
+
sthio
+
stbio
+
+
+
+
+
Other control instructions
+
+
+
trap
+
eret
+
break
+
bret
+
rdctl
+
wrctl
+
+
+
flushd
+
flushda
+
flushi
+
initd
+
initda
+
initi
+
+
+
flushp
+
sync
+
+
+
+
+
Program control instructions
+
+
+
callr
+
ret
+
jmp
+
call
+
jmpi
+
br
+
+
+
bge
+
bgeu
+
blt
+
bltu
+
beq
+
bne
+
+
+
bgt
+
bgtu
+
ble
+
bleu
+
+
+
+
+
Shift and rotate instructions
+
+
+
rol
+
ror
+
sll
+
sra
+
srl
+
roli
+
+
+
slli
+
srai
+
srli
+
+
+
+
+
+
Implemented control registers
+
+
+
+
Register
+
Name
+
Remarks
+
+
+
0
+
status
+
Only RSIE constant at 1 and PIE
+
+
+
1
+
estatus
+
+
+
+
+
2
+
bstatus
+
+
+
+
+
3
+
ienable
+
Number of bits depends on Number of IRQ lines
+ attribute.
+
+
+
4
+
ipending
+
Number of bits depends on Number of IRQ lines
+ attribute.
The pins are defined by a VHDL entity. The usage of the signals depends on the TCL file. To use the signals in the TCL file, you have to use the same name as defined in the component.
+
+
Attributes
+
+
+
TCL content file
+
The TCL script that will be executed. See section below for additionnal information about this script.
+
+
TCL interface VHDL entity
+
The VHDL entity that will define the component's interface.
The TCL script is launched by a Logisim into a wrapper.
+
+
Wrapper API
+
The wrapper serves an API that is compatible with the Questasim/Modelsim API to run simulations. Only a few functions are proposed :
+
+
+
examine <signal>
+
Gets a buffered signal value. The returned value is a string with the binary value of the signal.
+
<signal> the signal name. If it has a path to the signal (for Questasim), the path will be ignore (eg. /top_sim/component2/Signal_2_i will become Signal_2_i.
+
Single bit read (eg. examine Signal_2_i(3)) is not supported.
+
+
force <signal> <value>
+
Set a buffered signal value.
+
<signal> the signal name. If it has a path to the signal (for Questasim), the path will be ignore (eg. /top_sim/component2/Signal_2_i will become Signal_2_i.
+
<value> string of the binary value. If the string is incomplete (MSB missing) it will be completed by X (eg. 10100 set to a 8 bits signal becomes XXX10100).
+
+
run
+
Request a single simulation step to Logisim.
+
+
+
Wrapper callback
+
At each simulation step, the wrapper calls a refresh {} callback. You may usually put the code necessary to read the inputs, compute the output, refresh the GUI and set the outputs in this wrapper.
+
The refresh callback is not allowed to contain the run function call. If you do so, you will create en infinite loop, as the run function makes a simulation step that will call the refresh callback.
The pins are defined by the standard REDS console. The usage of the signals depends on the TCL file. To use the signals in the TCL file, you have to use the same name as defined in the component.
+
+
Attributes
+
+
+
TCL content file
+
The TCL script that will be executed. See section below for additionnal information about this script.
2.0 Beta 13 (in Base library, moved to Wiring in 2.7.0)
+
Appearance:
+
+
+
+
Behavior
+
+
The clock toggles its output value on a regular schedule as long as
+ticks are enabled via the
+Simulate menu.
+(Ticks are disabled by default.)
+A "tick" is Logisim's unit of time; the speed at which ticks occur can
+be selected from the Simulate menu's Tick Frequency submenu.
+The clock's cycle can be configured using
+its High Duration and Low Duration attributes.
+
+
Note that Logisim's simulation of clocks is quite unrealistic: In
+real circuits, multiple clocks will drift from one another and will
+never move in lockstep. But in Logisim, all clocks experience ticks at
+the same rate.
+
+
Pins
+
+
A clock has only one pin, an output with a bit width of 1, whose
+value will represent the current value of the clock. The location of
+this pin is specified in the Facing attribute. The clock's value
+will toggle on its schedule whenever ticks are enabled, and it will
+toggle whenever it is clicked using the Poke
+Tool.
+
+
Attributes
+
+
When the component is selected or being added,
+the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The side of the component where its output pin should be.
+
+
High Duration
+
The length of time within each cycle that the clock's output should
+be 1.
+
+
Low Duration
+
The length of time within each cycle that the clock's output should
+be 0.
+
+
Label
+
The text within the label associated with the clock component.
+
+
Label Location
+
The location of the label relative to the component.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
Clicking a clock component will toggle its current output value
+immediately.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
Emits a single value onto a wire.
+For a power element, indicated by a triangle, this value will be one
+(or, if the Data Bits attribute is more than 1, an all-ones value).
+For a ground element, indicated by an arrow
+of three shortening parallel lines, this value will be zero
+(or, if the Data Bits attribute is more than 1, an all-zero value).
+
+
The same functionality can be achieved using the more versatile
+Constant component. The only reason to prefer
+ground and power is that they are standard electronic symbols.
+
+
Pins
+
+
There is only one pin, an output whose bit width matches the Data Bits
+attribute. The component constantly outputs the same value on this pin:
+for a ground component, the output is an all-zero value,
+and for a power component, the output is an all-one value.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction in which the arrow will point from the location of its pin.
2.0 Beta 1 (in Gates library, moved to Wiring in 2.7.0)
+
Appearance:
+
+
+
+
Behavior
+
+
Emits the value specified in its Value attribute.
+
+
Pins
+
+
There is only one pin, an output whose bit width matches the Data Bits
+attribute. The location of this pin is specified in the Facing
+attribute. The component constantly outputs on this pin whatever
+value specified in the Value attribute.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the hexademical digits '0' through '9' and 'a' through 'f' alter its Value attribute,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction in which the pin is located relative to where the
+value is drawn.
+
+
Data Bits
+
The bit width of the value placed onto the wire.
+
+
Value
+
The value, written in hexademical, that is emitted by the component.
+The number of bits used to specify the value cannot exceed the
+component's bit width.
The bit extender transforms a value into a value of another bit width.
+If it's being transformed into a smaller bit width,
+it is simply truncated to keep the lowest-order bits.
+If it's being transformed into a large bit width,
+the lowest-order bits are the same,
+and you have a choice about what the additional high-order bits will be:
+They can all be 0, all be 1, all match the input's sign bit
+(its highest-order bit), or the component can have an additional one-bit
+input that determines the identity of these other bits.
+
+
Pins
+
+
+
+
West edge (input, bit width from Bit Width In attribute)
+
The multi-bit input whose value is to be transformed.
+
+
East edge (output, bit width from Bit Width Out attribute)
+
The computed output.
+
+
North edge (input, bit width 1)
+
Specifies what the additional bits in the output should be.
+This pin is available only when the Extension Type attribute is Input.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits 0 through 9 alter the Bit Width In attribute
+and Alt-0 through Alt-9 alter its Bit Width Out attribute.
+
+
+
+
Bit Width In
+
The input's bit width.
+
+
Bit Width Out
+
The output's bit width.
+
+
Extension Type
+
Assuming the output bit width exceeds the input bit width,
+this attribute configures what the additional output bits should be.
+If Zero or One, the additional bits are 0 or 1 accordingly.
+If Sign, the additional bits are taken to match the highest-order bit in the input.
+And if Input, the component has a second input on its north side whose one-bit value is used for the additional bits.
2.0 Beta 1 (in Base library, moved to Wiring in 2.7.0)
+
Appearance:
+
+
+
+
Behavior
+
+
A pin is an output or an input to a circuit, depending on the value
+of its Output? attribute. In drawing a pin, Logisim represents output
+pins using a circle or rounded rectangle, and input pins are represented
+using squares or rectangles. In either case, the individual bits of the
+value being sent or received is displayed within the component (except
+within printer view, when the component only says how many bits wide the
+pin is).
+
+
A pin is a convenient component for interacting with a circuit, and
+beginning Logisim users need not use them in any other way. But a
+user building a circuit using several subcircuits (as described in the
+`Subcircuits' section of
+the User's Guide) will use pins also
+to specify the interface between a
+circuit and a subcircuit. In particular, a circuit layout's pin
+components define the pins that appear on the subcircuit component when
+the layout is used within another circuit. In such a circuit, the values
+sent and received to those locations on the subcircuit component are
+tied to the pins within the subcircuit layout.
+
+
Pins
+
+
A pin component has only one pin, which will be an input to the
+component if the pin is an output pin, and it will be an output to the
+component if the pin is an input pin. In either case, its bit width
+matches the Data Bits attribute, and its location is specified by the
+Facing attribute.
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute,
+the arrow keys alter its Facing attribute,
+and Alt with an arrow key alters its Label Location attribute.
+
+
+
+
Facing
+
The side of the component where its input/output pin should be.
+
+
Output?
+
Specifies whether the component is an output pin or an input pin.
+(Note that if the pin component is an input pin, then the pin that acts
+as its interface within the circuit will be an output, and vice versa.)
+
+
Data Bits
+
The number of bits for the value that the pin handles.
+
+
Three-state?
+
For an input pin, this configures whether the user can
+instruct the pin to emit unspecified (i.e., floating) values.
+The attribute deals with the user interface only; it does not have
+any effect on how the pin behaves when the circuit layout is used as a
+subcircuit.
+For an output pin, the attribute has no effect.
+
+
Pull Behavior
+
For an input pin, the attribute specifies how floating values should
+be treated when received as an input, perhaps from a circuit using the
+layout as a subcircuit. With "unchanged," the floating values are sent
+into the layout as floating values; with "pull up," they are converted
+into 1 values before being sent into the circuit layout; and with "pull
+down," they are converted into 0 values before being sent into the
+circuit layout.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Location
+
The location of the label relative to the component.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
Clicking an output pin has no effect, although the pin's attributes
+will be displayed.
+
+
Clicking an input pin will toggle the bit that is clicked. If it is a
+three-state pin, then the corresponding bit will rotate between the
+three states.
+
+
If, however, the user is viewing the state of a subcircuit
+as described in the `Debugging
+Subcircuits' of the User's Guide,
+then the pin's value is pinned to whatever value the subcircuit is
+receiving from the containing circuit. The user cannot change the value
+without breaking this link between the subcircuit's state and the
+containing circuit's state, and Logisim will prompt the user to verify
+that breaking this link is actually desired.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
A probe is an element that simply displays the value at a given point
+in a circuit. It does not itself interact with other components.
+
+
In most respects, the probe component duplicates the functionality
+found in a Pin component configured as an output
+pin. The primary difference is that if the circuit is used as a subcircuit
+component, then an output pin will be a part of that interface, whereas
+a probe is not. They also are different in that the probe does not have a Data Bits
+attribute to be configured: The bit width is inferred from whatever value it
+happens to see on its input. Graphically, they are similar but have slightly
+different borders: A pin has a thick, black border, whereas a probe has
+a thin, gray border.
+
+
Pins
+
+
A probe component has only one pin, which will acts as an input to
+the probe. The width that this pin accepts is adaptive: The probe will
+adapt to inputs of any width.
+
+
Attributes
+
+
When the component is selected or being added,
+the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The side of the component where its input pin should be.
+
+
Label
+
The text within the label associated with the component.
+
+
Label Location
+
The location of the label relative to the component.
+
+
Label Font
+
The font with which to render the label.
+
+
Radix
+
The base (for example, binary, decimal, or hexadecimal) in which
+a value is displayed.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the component to be edited.
When connected to a point,
+this component has an effect only when
+the value at that point is the floating value (Z).
+In this case, the resistor pulls the wire to which it is connected
+toward the value indicated in its Pull Direction attribute.
+
+
If it is connected to a multiple-bit value, then each bit in the
+value that is floating is pulled in the direction specified, while
+the bits that are not floating are left unchanged.
+
+
Pins
+
+
The resistor has just one pin, which is an output and has a bit
+width that is derived from whichever component it is connected.
+
+
Attributes
+
+
When the component is selected or being added,
+the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction in which the component's pin lies from component's center.
+
+
Pull Direction
+
Specifies the value to which a floating value should be pulled. This could be 0, 1, or the error value.
2.0 Beta 1 (in Base library, moved to Wiring in 2.7.0)
+
Appearance:
+
+
+
+
Behavior
+
+
The splitter creates a correspondence between a multi-bit value and several
+separate subsets of those bits. Despite its name, it can either
+split a multi-bit value into component parts, or it can combine
+component parts into a multi-bit value - or indeed it can do both at once.
+A more complete description of splitters is found in the `Splitters' section of the
+User's Guide.
+
+
Logisim treats splitters specially when propagating values within a
+circuit: Whereas all other components have a computed delay for purposes
+of simulating their behavior, values propagate through splitters (as
+well as wires) instantaneously.
+
+
Note: The term splitter is a non-standard
+term, which is unique to Logisim as far as I know. I am unaware of any
+standard term for such a concept; the only term I have heard used is
+bus ripper, but this term is unnecessarily violent for my
+tastes.
+
+
Pins
+
+
To distinguish the several connecting points for a splitter, we refer
+to the single connecting point one side as its combined end,
+and we refer to the multiple connecting points on the other side as its
+split ends.
+
+
+
+
Combined end (input/output bit width matches Bit Width In attribute)
+
A value holding all of the bits traveling through the splitter.
+
+
Split ends (input/output, bit width computed based on Bit x attributes)
+
The number of split ends is specified in the Fan Out attribute, and
+each split end has an index that is at least 0 and less than the Fan Out
+attribute. For each split end, all bits for which Bit x
+refers to its index travels through that split end; the order of these
+bits is the same as their order within the combined end.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+the digits '0' through '9' alter its Fan Out attribute,
+Alt-0 through Alt-9 alter both the Fan Out and Bit Width In attributes,
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The location of the split ends relative to the combined end.
+
+
Fan Out
+
The number of split ends.
+
+
Bit Width In
+
The bit width of the combined end.
+
+
Appearance
+
Supports different ways of depicting the splitter in the circuit.
+The Left-handed option (the default) draws a spine going left from the
+combined end, with a labeled line coming from the spine for each split end.
+The Right-handed option is the same except the spine goes right (if you're
+facing according to the Facing attribute).
+The Centered option centers the spine so it goes in roughly equal directions
+left and right.
+And the Legacy option draws diagonal lines to each split end, without labels;
+this option is primarily for compatibility with versions
+older than 2.7.0, when this was the only option for splitter appearance.
+
+
Bit x
+
The index of the split end to which bit x of the combined
+end corresponds. The split ends are indexed starting from 0 at the top
+(for a splitter facing east or west) or from 0 at the left/west (for a
+splitter facing north or south). A bit can be specified to correspond to
+none of the split ends. There is no way for a bit to correspond to
+multiple split ends.
+
+
Sometimes you can avoid twiddling each individual Bit x attribute
+by bringing up the pop-up menu for a splitter (usually by right-clicking or
+control-clicking it). The pop-up menu includes options labeled Distribute Ascending
+and Distribute Descending. The Distribute Ascending option distributes the bits
+so that each split end receives the same number of bits, starting from end 0.
+(If the number of split ends doesn't divide exactly into the number of bits,
+then the bits are distributed as evenly as possible.)
+Distribute Descending does the same but starts from the highest-numbered end.
A transistor has two inputs, called gate and source,
+and one output, called drain. When diagrammed, the source
+input and drain output are drawn connected by a plate;
+Logisim draws an arrowhead to indicate the direction of flow from input to output.
+The gate input is drawn connected to a plate that is parallel to the
+plate connecting source to drain. Logisim supports two types of
+transistors, with slightly different behaviors described below; the P-type
+transistor is indicated by a circle connecting the gate input to its
+plate, while the N-type transistor has no such circle.
+
+
Depending on the value found at gate,
+the value at source may be transmitted to
+drain; or there may be no connection from source,
+so drain is left floating. The determination of transmitting or disconnecting
+depends on the type of transistor: A P-type transistor
+(indicated by a circle on the gate line) transmits
+when gate is 0, while an N-type transistor (which has no such circle)
+transmits when gate is 1. The behavior is summarized by the
+following tables.
+
+
+
+
P-type
+
+
+
gate
+
0
1
X/Z
+
0
+
0
Z
X
+
source
1
+
1
Z
X
+
Z
+
Z
Z
Z
+
X
+
X
Z
X
+
+
N-type
+
+
+
gate
+
0
1
X/Z
+
0
+
Z
0
X
+
source
1
+
Z
1
X
+
Z
+
Z
Z
Z
+
X
+
Z
X
X
+
+
+
Or in summarized form:
+
+
+
+
P-type
+
+
+
gate
drain
+
0
source
+
1
Z
+
X/Z
X*
+
+
N-type
+
+
+
gate
drain
+
0
Z
+
1
source
+
X/Z
X*
+
+
* If source is Z, drain is Z; otherwise drain is X.
+
+
+
If the Data Bits attribute is more than 1, the gate input is still
+a single bit, but its value is applied simultaneously to each of the
+source input's bits.
+
+
An N-type transistor behaves very similarly to a
+Controlled Buffer. The primary difference
+is that a transistor is meant for more basic circuit designs.
+
+
Pins (assuming component faces east, gate line top/left)
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The component's source input that will transmit to the output
+if triggered by the gate input.
+
+
North edge (input, bit width 1)
+
The component's gate input. For P-type transistors, the transistor
+will transmit if the gate value is 0; for N-type transistors,
+this will trigger the transistor if the gate value is 1.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The component's output, which will match the source input
+if indicated by the gate input, or will be floating if the gate
+input is the negation of what indicates negation. If gate is floating
+or an error value, then the output will be an error value.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Type
+
Determines whether the transistor is P-type or N-type.
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Gate Location
+
The location of the gate input.
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
A transmission gate has three inputs,
+called source, n-gate, and p-gate;
+and it has one output, called drain. When diagrammed, the source
+input and drain output are drawn connected by two plates;
+Logisim draws an arrowhead to indicate the direction of flow from input to output.
+The two gate inputs are drawn as lines connected to plates parallel to
+each of the plates connecting source to drain.
+The p-gate input's line has a circle, while the n-gate input's line does not.
+
+
+
p-gate
+
source
+
+
drain
+
n-gate
+
+
+
The transmission gate is simply the combination of two complementary
+transistors. Indeed, the same behavior can be achieved in Logisim by using just
+one transistor. However, designers sometimes prefer to use matched pairs of
+transistors due to electrical issues with draining voltage
+that is more complex than Logisim attempts to simulate.
+
+
The values at n-gate and p-gate are expected to be
+opposite to each other. If p-gate is 0 while n-gate is 1,
+then the value found at source is transmitted to drain.
+If p-gate is 1 while p-gate is 0, then the connection is broken,
+so the value at drain is left floating. In all other cases, drain
+receives an error output — unless source is floating,
+in which case drain is floating as well. This behavior is summarized by the following table.
+
+
+
p-gate
n-gate
drain
+
0
0
X*
+
0
1
source
+
1
0
Z
+
1
1
X*
+
X/Z
any
X*
+
any
X/Z
X*
+
+
* If source is Z, drain is Z; otherwise drain is X.
+
+
+
If the Data Bits attribute is more than 1, each gate input is still
+a single bit, but the gate values are applied simultaneously to each of the
+source input's bits.
+
+
Pins (assuming component faces east, gate line top/left)
+
+
+
+
West edge (input, bit width matches Data Bits attribute)
+
The component's source input that will transmit to the output
+if triggered by the p-gate and n-gate inputs.
+
+
North edge (input, bit width 1)
+
The component's p-gate input.
+
+
South edge (input, bit width 1)
+
The component's n-gate input.
+
+
East edge (output, bit width matches Data Bits attribute)
+
The component's output, which will match the source input
+if p-gate is 0 and n-gate is 1, or it will be floating if
+p-gate is 1 and n-gate is 0. For all other values on p-gate and n-gate,
+the output is an error value.
+
+
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction of the component (its output relative to its input).
+
+
Gate Location
+
The location of the gate input.
+
+
Data Bits
+
The bit width of the component's inputs and outputs.
A tunnel acts like a wire in that it binds points together,
+but unlike a wire the connection is not explicitly drawn.
+This is helpful when you need to connect points far apart in the circuit
+and a network of wires would make the circuit much more ugly.
+The below illustration illustrates how this works.
+
+
+
+
Here, all three tunnels have the same label, a, and so
+the three points to which the tunnels point are connected.
+(If one of the tunnels were labeled something else, like b,
+then it would be part of a different set of tunnels.)
+The controlled buffer at top emits a floating output
+since its lower input is 0.
+This normally leads the wire coming from the controlled buffer to be blue;
+but here it is dark green because the floating output combines
+through the tunnel with the 0 from the pin at bottom.
+If the control input into the buffer changes to 1,
+then the controlled buffer would feed 1 into the tunnel,
+which would combine with 0 from the pin at bottom to result in an error value; thus, we would then see red wires feeding through all three tunnels.
+
+
Pins
+
+
A tunnel has only one pin, whose bit width matches the tunnel's
+Data Bits attribute. This pin is neither an input nor an output —
+the matching tunnels are simply connected transparently.
+
+
Attributes
+
+
When the component is selected or being added,
+Alt-0 through Alt-9 alter its Data Bits attribute
+and the arrow keys alter its Facing attribute.
+
+
+
+
Facing
+
The direction toward which the tunnel points.
+
+
Data Bits
+
The number of bits for the tunnel.
+
+
Label
+
The text within the label associated with the tunnel.
+This tunnel is connected to all other tunnels with exactly the same label.
+
+
Label Font
+
The font with which to render the label.
+
+
+
+
Poke Tool Behavior
+
+
None.
+
+
Text Tool Behavior
+
+
Allows the label associated with the tunnel to be edited.