Skip to content

Commit

Permalink
docs: updated docs to use differed URLs in markdown links and also up…
Browse files Browse the repository at this point in the history 
…dated the comparison table
  • Loading branch information
@lethalbit
lethalbit committed Mar 10, 2024
1 parent b167528 commit c418548
Show file tree
Hide file tree
Showing 12 changed files with 147 additions and 73 deletions.
8 changes: 5 additions & 3 deletions docs/applets/api/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
:hidden:
cli
repl
applet
device
```
Expand All @@ -15,9 +14,9 @@ Flesh this out

The following APIs are available for use within Squishy applets. They allow the applet
to register various components with the Squishy framework, such as the
[CLI](./cli.md), or the [REPL](./repl.md). Out of the three subsystems, only the CLI is mandatory, the GUI and REPL are optional.
[CLI]. Out of the three subsystems, only the CLI is mandatory, the GUI and REPL are optional.

For details on how to write Squishy applets, see the [Applets Tutorial](../../tutorials/applets/index.md) for a walk-through.
For details on how to write Squishy applets, see the [Applets Tutorial] for a walk-through.

## Applet Search Locations

Expand Down Expand Up @@ -47,3 +46,6 @@ The second location Squishy searches for applets in is partially platform depend
```

[Applets Tutorial]: ../../tutorials/applets/index.md
[CLI]: ./cli.md
9 changes: 0 additions & 9 deletions docs/applets/api/repl.md
View file

This file was deleted.

11 changes: 8 additions & 3 deletions docs/applets/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,16 @@ Flesh this section out
```


Squishy allows for the development of modular pieces of combined code and [Torii HDL](https://github.com/shrine-maiden-heavy-industries/torii-hdl) gateware called an applet. It gives Squishy it's functionality and allows for the extension of said functionality and/or entirely new custom functionality.
Squishy allows for the development of modular pieces of combined code and [Torii HDL] gateware called an applet. It gives Squishy it's functionality and allows for the extension of said functionality and/or entirely new custom functionality.


There are currently two built-in applets, the [analyzer](./analyzer.md), and [taperipper](./taperipper.md) applets. With more built-in applets are planned for the future.
There are currently two built-in applets, the [analyzer], and [taperipper]applets. With more built-in applets are planned for the future.

Squishy allows you to run your own custom applets, any python packages in the `SQUISHY_APPLETS` directory are attempted to be loaded as an applet, and then exposed to the user to allow them to invoke.

For more details on custom applets, see the [Custom Applet](../tutorials/applets/index.md) tutorial for a walkthrough of developing your own Squishy applet.
For more details on custom applets, see the [Custom Applet] tutorial for a walkthrough of developing your own Squishy applet.

[Custom Applet]: ../tutorials/applets/index.md
[analyzer]: ./analyzer.md
[taperipper]: ./taperipper.md
[Torii HDL]: https://github.com/shrine-maiden-heavy-industries/torii-hdl
10 changes: 8 additions & 2 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
# Frequently Asked Questions

The following are some commonly asked questions, while this section is not exhaustive it will be updated when appropriate. For more specific questions, please join the IRC channel [#squishy on libera.chat](https://web.libera.chat/#squishy) or use the [GitHub Discussions](https://github.com/squishy-scsi/squishy/discussions).
The following are some commonly asked questions, while this section is not exhaustive it will be updated when appropriate. For more specific questions, please join the IRC channel [#squishy on libera.chat] or use the [GitHub Discussions].


## Why Does Squishy not have a Discord?

Squishy likes to do things out in the open, this means that Discords model of walled-off communities is not conducive to how we want to do things. In addition to this, there is a trend to moving documentation away from things like Wiki's and websites into Discord servers, which causes that information to no longer be publicly accessible, this is a huge problem when it comes to things like Open Source projects such as Squishy.

All in all, to make things easier on both the maintainers and community members, we are staying away from Discord for the forseeable future. We have an <a href="irc://irc.libera.chat:6667/#squishy">IRC chanel</a> for developer talk and general chatting, and for everything else we have the [GitHub Discussions](https://github.com/squishy-scsi/squishy/discussions), Issue tracker, and this website.
All in all, to make things easier on both the maintainers and community members, we are staying away from Discord for the forseeable future. We have an <a href="irc://irc.libera.chat:6667/#squishy">IRC chanel</a> for developer talk and general chatting, and for everything else we have the [GitHub Discussions], [Issue tracker], and this website.



[#squishy on libera.chat]: https://web.libera.chat/#squishy
[GitHub Discussions]: https://github.com/squishy-scsi/squishy/discussions,
[Issue tracker]: https://github.com/squishy-scsi/squishy/issues
5 changes: 4 additions & 1 deletion docs/getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

# Getting Started

To get started with Squishy, first follow the [installation](install.md) instructions before you continue.
To get started with Squishy, first follow the [installation] instructions before you continue.


## Connecting the Hardware
Expand All @@ -20,3 +20,6 @@ Write this section
```{todo}
Write this section
```


[installation]: ./install.md
15 changes: 11 additions & 4 deletions docs/hardware/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Both the revision and the release level start at 0, and increment by one. If the

The format follows the `rev<#>[.#]` format, where `rev<#>` is the hardware revision and `[.#]` is the release level. so the following string, `rev8.3` is hardware revision 8, release 3.

Currently there are two hardware releases [`rev1`](./rev1.md) and [`rev2`](./rev2.md), see each page for details on each respective hardware revision.
Currently there are two hardware releases [`rev1`] and [`rev2`], see each page for details on each respective hardware revision.



Expand All @@ -32,7 +32,7 @@ There are two main ways to get squishy hardware, buying it, or building it.
### Buying Hardware

```{note}
As of 2022-04-24, Squishy hardware is not available for sale, however, once engineering and validation of Revision 2 is completed, rev2 units are expected to be available to purchase.
As of 2024-03-10, Squishy hardware is not available for sale, however, once engineering and validation of Revision 2 is completed, rev2 units are expected to be available to purchase.
```

### Building Hardware
Expand All @@ -43,9 +43,16 @@ The smallest parts are 0402 and all revisions contain at least one large BGA par

### Provisioning the Hardware

If you buy a pre-built Squishy, it will already be provisioned, but in case something goes catastrophically wrong with an update, or you build your own hardware, see the section on [provisioning](../tutorials/provisioning.md) to learn how to provision new hardware or re-provision existing hardware.
If you buy a pre-built Squishy, it will already be provisioned, but in case something goes catastrophically wrong with an update, or you build your own hardware, see the section on [provisioning] to learn how to provision new hardware or re-provision existing hardware.


### Work-In-Progress Hardware

The hardware is always a work in progress, you can view a live rendering of the WIP hardware in your web browser [here](https://kicanvas.org/?github=https%3A%2F%2Fgithub.com%2Fsquishy-scsi%2Fhardware%2Ftree%2Fmain%2Fboards%2Fsquishy), thanks to [KiCanvas](https://kicanvas.org).
The hardware is always a work in progress, you can view a live rendering of the WIP hardware in your web browser [here](https://kicanvas.org/?github=https%3A%2F%2Fgithub.com%2Fsquishy-scsi%2Fhardware%2Ftree%2Fmain%2Fboards%2Fsquishy), thanks to [KiCanvas].


[provisioning]: ../tutorials/provisioning.md
[`rev1`]: ./rev1.md
[`rev2`]: ./rev2.md
[here]: https://kicanvas.org/?github=https%3A%2F%2Fgithub.com%2Fsquishy-scsi%2Fhardware%2Ftree%2Fmain%2Fboards%2Fsquishy
[KiCanvas]: https://kicanvas.org
2 changes: 1 addition & 1 deletion docs/hardware/rev1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Flesh this section out
```
```{warning}
This hardware revision has [errata](#errata)!
This hardware revision should be considered non-functional and is kept in the documentation for historical purposes only.
```


Expand Down
86 changes: 56 additions & 30 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,62 +27,88 @@ Hardware <https://github.com/squishy-scsi/hardware>
:figwidth: 350px
```

This is the documentation for [Squishy](https://github.com/squishy-scsi/squishy) and it's supporting components, as well as a collection of guides and tutorials for the Squishy ecosystem.
This is the documentation for [Squishy] and it's supporting components, as well as a collection of guides and tutorials for the Squishy ecosystem.


## What Squishy Isn't

It's important to detail what Squishy isn't, as it differs a lot from other devices intended to interact with older SCSI systems.

Squishy is not *only* a disk emulator like the [BlueSCSI](https://scsi.blue/) or the [SCSI2SD](https://www.codesrc.com/mediawiki/index.php?title=SCSI2SD). It is also not *only* a SCSI to USB Mass storage adapter.
Squishy is not *only* a disk emulator like the [BlueSCSI] or the [SCSI2SD]. It is also not *only* a SCSI to USB Mass storage adapter.

Squishy is not a *specialized* device targeting only a single aspect of the SCSI ecosystem, nor targeting only a single platform.

## What Squishy Is

Squishy is a platform, it allows you to accomplish almost any goal you wish to that involves a SCSI bus. It can do things as mundane as emulating a SCSI hard drive, but also you can use it to [sniff, analyze, and reply SCSI bus traffic](./applets/analyzer.md), or even [boot a modern system from 9-track tape](./applets/taperipper.md).
Squishy is a platform, it allows you to accomplish almost any goal you wish to that involves a SCSI bus. It can do things as mundane as emulating a SCSI hard drive, but also you can use it to [sniff, analyze, and replay SCSI bus traffic], or even [boot a modern system from 9-track tape].

It is comprised of a [gateware](./library/gateware/index.md) and [python](./library/python/index.md) library as well as a [hardware](./hardware/index.md) platform that acts as a bridge between the software and SCSI bus. Squishy allows for powerful and flexible control over all things SCSI, and using its [powerful applet system](./applets/index.md) it gives that power to you.
It is comprised of a [gateware] and [python] library as well as a [hardware] platform that acts as a bridge between the software and SCSI bus. Squishy allows for powerful and flexible control over all things SCSI, and using its [powerful applet system] it gives that power to you.


For a more detailed introduction to Squishy and it's components, see the [Introduction](./introduction.md) section of the documentation. Then, when you're ready visit the [Getting Started](./getting_started.md) section to get up an running.
For a more detailed introduction to Squishy and it's components, see the [Introduction] section of the documentation. Then, when you're ready visit the [Getting Started] section to get up an running.

Squishy is entirely open source, and under permissive licenses. The full source code, gateware, firmware, and hardware designs are available on [GitHub](https://github.com/squishy-scsi/squishy).
Squishy is entirely open source, and under permissive licenses. The full source code, gateware, firmware, and hardware designs are available on [GitHub].

## Comparison

| | [Squishy](https://scsi.moe) | [BlueSCSI](https://scsi.blue/) | [SCSI2SD](https://www.codesrc.com/mediawiki/index.php/SCSI2SD) | [PiSCSI](https://github.com/PiSCSI/piscsi) |
|-----------------------|----------------|----------------|---------|--------------------|
| Has a cute mascot | Yes | No | No | No |
| Device Emulation | Yes | Yes | Yes | Yes |
| Non-Storage Emulation | Yes | No | No | Yes<sup>1</sup> |
| Initiator Emulation | Yes | No | No | Yes<sup>1</sup> |
| Passive Bus Tapping | Yes | No | No | Yes |
| Fully Open Source | Yes | No<sup>2</sup> | No | No<sup>2</sup> |
| SCSI-1 Support | Yes | No | No | No |
| SCSI-2 Support | Yes | Yes? | Yes | Yes |
| SCSI-3 Support | Yes | No | No | No |
| HVD Support | Yes | No | No | No |
| LVD Support | Yes | No | No | No |
| SE Support | Yes | Yes | Yes | Yes |
| Fastest Bus Speed | Nyoomie | ? | FAST10 | ? |
| Standalone | No<sup>3</sup> | Yes | Yes | Yes |
| Cost | ? | ~50USD | ~98USD | ~45USD<sup>4</sup> |
| | [Squishy] | [BlueSCSI] | [SCSI2SD] | [PiSCSI] |
|-----------------------|------------------------|-----------------|-----------|--------------------|
| Has a cute mascot | Yes | No | No | No |
| Device Emulation | Yes | Yes | Yes | Yes |
| Non-Storage Emulation | Yes | Yes<sup>1</sup> | No | Yes<sup>2</sup> |
| Initiator Emulation | Yes | Yes | No | Yes<sup>2</sup> |
| Passive Bus Tapping | Yes | No? | No | Yes |
| Fully Open Source | Yes | Yes | No | No<sup>3</sup> |
| SCSI-1 Support | Yes | Yes | No | No |
| SCSI-2 Support | Yes | Yes | Yes | Yes |
| SCSI-3 Support | Yes | No | No | No |
| HVD Support | Yes | No | No | No |
| LVD Support | Yes | No | No | No |
| SE Support | Yes | Yes | Yes | Yes |
| Fastest Bus Speed | ULTRA320<sup>4,5</sup> | FAST10 | FAST10 | FAST10? |
| Standalone | No<sup>6</sup> | Yes | Yes | Yes |
| Cost | ?<sup>7</sup> | ~50USD | ~98USD | ~50USD<sup>8</sup> |

**1:** PiSCSI allows you to write Linux userspace software via an API.
<small>**1:** Only supports DaynaPORT emulation.</small>

**2:** The adapter board is Open Source, but the main compute element is not.
<small>**2:** PiSCSI allows you to write Linux userspace software via an API.</small>

**3:** Squishy requires USB power for operation, therefore it is considered to always be tethered.
<small>**3:** The adapter board is Open Source, but the main compute element is not.</small>

<small>**4:** Depends on the SCSI PHY Module and interface adapter.</small>

<small>**5:** Only ULTRA320 SCSI speeds are guaranteed, however, depending on the silicon lottery ULTRA640 may be achievable.</small>

<small>**6:** Squishy requires USB power for operation, therefore it is considered to always be tethered.</small>

<small>**7:** Due to the hardware not being 100% complete an accurate cost is not available yet.</small>

<small>**8:** This includes only the PiSCSI interface itself, and not the needed RaspberryPi SOM as well.</small>

**4:** This includes only the PiSCSI interface itself, and not the needed RaspberryPi SOM as well.

## Community

Squishy has a dedicated IRC channel, [#squishy on libera.chat](https://web.libera.chat/#squishy). Join to ask questions, discuss ongoing development, or just hang out.
Squishy has a dedicated IRC channel, [#squishy on libera.chat]. Join to ask questions, discuss ongoing development, or just hang out.

There are also [GitHub Discussions](https://github.com/squishy-scsi/squishy/discussions) enabled on the repository if you have any questions or comments.
There are also [GitHub Discussions] enabled on the repository if you have any questions or comments.


```{note}
Squishy does not have an official discord, nor any endorsed discord servers, for an explanation as to why, see the [F.A.Q.](./faq.md)
Squishy does not have an official discord, nor any endorsed discord servers, for an explanation as to why, see the [F.A.Q.]
```
[sniff, analyze, and replay SCSI bus traffic]: ./applets/analyzer.md
[boot a modern system from 9-track tape]: ./applets/taperipper.md
[gateware]: ./library/gateware/index.md
[python]: ./library/python/index.md
[hardware]: ./hardware/index.md
[powerful applet system]: ./applets/index.md
[Introduction]: ./introduction.md
[Getting Started]: ./getting_started.md
[GitHub]: https://github.com/squishy-scsi/squishy
[Squishy]: https://github.com/squishy-scsi/squishy
[BlueSCSI]: https://scsi.blue/
[SCSI2SD]: https://www.codesrc.com/mediawiki/index.php/SCSI2SD
[PiSCSI]: https://github.com/PiSCSI/piscsi
[#squishy on libera.chat]: https://web.libera.chat/#squishy
[GitHub Discussions]: https://github.com/squishy-scsi/squishy/discussions
[F.A.Q.]: ./faq.md
Loading

0 comments on commit c418548

Please sign in to comment.