docs/develop: More reorganization.
* There is now a 'busses' folder, and the extant USB/SDHCI/Bluetooth/etc. docs now live in it, instead of various other places. * kernel/ports is now kernel/arch, like it is in src/system. SPARC documentation is now in there, too. * VM files (these are rather outdated) are now in kernel/vm. * SCSI ASC info removed, this is easily available online and it doesn't seem to be very relevant.
This commit is contained in:
Augustin Cavalier
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
@@ -0,0 +1,17 @@
|
||||
(Copied mostly from <http://urnenfeld.blogspot.de/2012/07/in-past-i-got-to-know-that-motivation.html>)
|
||||
|
||||
**L2cap under `network/protocols/l2cap`**: Provides socket interface to have l2cap channels. L2CAP offers connection oriented and connectionless sockets. But bluetooth stack as this point has no interchangeability with TCP/IP, A Higher level Bluetooth profile must be implemented
|
||||
|
||||
**HCI under `src/add-ons/kernel/bluetooth`**: Here we have 2 modules, one for handling global bluetooth data structures such as connection handles and L2cap channels, and frames
|
||||
|
||||
**H2generic under `src/add-ons/kernel/drivers/bluetooth`**: The USB driver, implementing the H2 transport.
|
||||
|
||||
**Bluetooth kit under `src/kit/bluetooth`**: C++ implementation based on JSR82 api.
|
||||
|
||||
**Bluetooth Server under `src/servers/bluetooth`**: Basically handling opened devices (local connected fisically in our system) and forwaring kit calls to them.
|
||||
|
||||
**Bluetooth Preferences under `src/preferences/bluetooth`**: Configuration using the kit
|
||||
|
||||
**Test applications under `src/tests/kits/bluetooth`**.
|
||||
|
||||
There is a small prototype component which is not here documented below src/add-ons/bluetooth/ResetLocalDevice. Its intention was to be an add-on of bluetooth preferences, So that new HCI commands could be customized by users or external developers. I did not like at the end the idea, I did not find the flexibility I wanted.
|
||||
@@ -0,0 +1,175 @@
|
||||
# SDHCI MMC Driver
|
||||
|
||||
This driver project is a part of GSoC'18 and is aimed at providing support for
|
||||
PCI devices with class 8 and subclass 5 over x86 architecture. This document
|
||||
will make you familiar with the [code produced during GSoC](https://review.haiku-os.org/#/c/haiku/+/318/),
|
||||
loading and testing the driver(including hardware emulation), insight into the
|
||||
code and future tasks.
|
||||
|
||||
For detailed explanations about the project, you can refer the
|
||||
[weekly reports](https://www.haiku-os.org/blog/krish_iyer) and comment issues
|
||||
if any. For this project we have referred [SD Host Controller Spec Version 1.00](https://www.sdcard.org/downloads/pls/pdf/index.php?p=PartA2_SD_Host_Controller_Simplified_Specification_Ver1.00.jpg&f=PartA2_SD_Host_Controller_Simplified_Specification_Ver1.00.pdf&e=EN_A2100)
|
||||
and [Physical Layer Spec Version 1.10](https://www.sdcard.org/downloads/pls/pdf/index.php?p=Part1_Physical_Layer_Simplified_Specification_Ver1.10.jpg&f=Part1_Physical_Layer_Simplified_Specification_Ver1.10.pdf&e=EN_P1110).
|
||||
|
||||
## Loading and testing the driver
|
||||
### Emulating the hardware
|
||||
|
||||
We will emulate a SDHC device using qemu as all system may not have the device.
|
||||
These days systems provide transfer to SD/ MMC card over USB. The document will
|
||||
not instruct you on how to build haiku but you can refer the link to
|
||||
[compile and build the haiku images](https://www.haiku-os.org/guides/building/)
|
||||
or the [week #1 and #2](https://www.haiku-os.org/blog/krish_iyer/2018-05-06_gsoc_2018_sdhci_mmc_driver_week_1_and_2/)
|
||||
project report will also work.
|
||||
|
||||
After building the image, we will emulate the hardware and host haiku on top of that.
|
||||
|
||||
#### Emulation
|
||||
For emulating a sdhci-pci device
|
||||
|
||||
qemu-img create sd-card.img 10G
|
||||
qemu-system-x86_64 ~/haiku/generated.x86_64/haiku.image -hdd haiku_drive_2.img -device sdhci-pci -device sd-card,drive=mydrive -drive if=sd,index=0,file=sd.img,format=raw,id=mydrive -m 512M -enable-kvm
|
||||
|
||||
### Testing and loading the driver
|
||||
The code is merged but not part of the default build
|
||||
because it's not useful for end users currently. In order to add the drivers
|
||||
to the image and load them, we need to adjust some buildfiles.
|
||||
|
||||
The required changes are in [this changeset](https://review.haiku-os.org/c/haiku/+/448/8).
|
||||
|
||||
## Insight into the code and future tasks
|
||||
### Directory and files where all the code related to the project resides
|
||||
|
||||
#### MMC Bus
|
||||
* src/add-ons/kernel/busses/mmc
|
||||
* sdhci-pci.cpp
|
||||
* sdhci-pci.h
|
||||
* Jamfile
|
||||
#### The Bus Manager
|
||||
* src/add-ons/kernel/bus_managers/mmc
|
||||
* mmc_bus.cpp
|
||||
* mmc_module.cpp
|
||||
* mmc_bus.h
|
||||
* Jamfile
|
||||
#### Disk Driver
|
||||
* src/add-ons/kernel/drivers/disk/mmc
|
||||
* mmc_disk.cpp
|
||||
* mmc_disk.h
|
||||
* Jamfile
|
||||
#### Hardcoding the driver
|
||||
* src/system/kernel/device_manager
|
||||
* device_manager.cpp
|
||||
### Insight into the code
|
||||
#### MMC Bus management overview
|
||||
|
||||
The device tree for MMC support looks like this:
|
||||
|
||||
* PCI bus manager
|
||||
* (other PCI devices)
|
||||
* SDHCI controller
|
||||
* SDHCI bus
|
||||
* MMC bus manager
|
||||
* MMC device
|
||||
* mmc\_disk device
|
||||
* MMC device
|
||||
* (other SDIO driver)
|
||||
* MMC bus manager (second MMC bus)
|
||||
* MMC device
|
||||
* mmc\_disk device
|
||||
|
||||
At the first level, the PCI bus manager publishes a device node for each device
|
||||
found. One of them is our SDHCI controller, identified either by the PCI device
|
||||
class and subclass, or for not completely SDHCI compatible device, by the
|
||||
device and vendor IDs.
|
||||
|
||||
The SDHCI bus driver attaches to this device and publishes his own node. It
|
||||
then scans the device and publishes an MMC bus node for each slot (there may
|
||||
be multiple SD slots attached to a single PCI controller).
|
||||
|
||||
The MMC bus manager then attach to each of these slots, and send the appropriate
|
||||
commands for enumerating the SD cards (there may be multiple cards in a "slot"),
|
||||
and publishes a device node for each of them. Finally, the mmc\_disk driver can
|
||||
bind itself to one of these device nodes, and publish the corresponding disk
|
||||
node, which is also be made available in /dev/disk/mmc.
|
||||
|
||||
Currently the mmc bus does not publish anything in the devfs, but this could be
|
||||
added if sending raw SD/MMC commands to SD cards from userland is considered
|
||||
desirable.
|
||||
|
||||
#### SDHCI driver
|
||||
|
||||
The SDHCI driver is the lowest level of the MMC stack. It provides abstraction
|
||||
of the SDHCI device. Later on, different way to access an SD bus may be added,
|
||||
for example for ARM devices which decided to use a different register interface.
|
||||
|
||||
The entry point is as usual **supports\_device()**. This method is called only
|
||||
for devices which may be SDHCI controllers, thanks to filtering done in the
|
||||
device manager to probe only the relevant devices. The probing is done on-demand,
|
||||
currently when the system is enumerating /dev/disk in the devfs. Later on, when
|
||||
we have SDIO support, probing will also be triggered in other cases.
|
||||
|
||||
The function identifies the device by checking the class and subclass, as well
|
||||
as a limited set of hardcoded PCI device and vendor IDs for devices that do not
|
||||
use the assigned subclass.
|
||||
|
||||
Once a compatible device is found, **register\_child\_devices()** is used to
|
||||
publish device nodes for each slot to be controlled by the mmc bus manager.
|
||||
The registers for each device are mapped into virtual memory, using the
|
||||
information from the PCI bar registers. **struct registers** is defined so that
|
||||
it matches the register layout, and provide a little abstraction to raw register
|
||||
access.
|
||||
|
||||
An SdhciBus object is created to manage each of these busses at the SDHCI level.
|
||||
It will be responsible for executing SD commands on that bus, and dealing with
|
||||
the resulting interrupts.
|
||||
|
||||
#### The Bus Manager
|
||||
|
||||
The MMC bus manager manages the MMC bus (duh). Its tasks are:
|
||||
|
||||
* enumerating SD cards on the bus
|
||||
* assigning RCAs to the cards for identifying them when sending commands
|
||||
* setting the bus clock speed according to what the cards can handle
|
||||
* remember which SD card is currently active (CMD7)
|
||||
* manage cards state
|
||||
* publish device nodes for each card
|
||||
|
||||
#### Disk Driver
|
||||
|
||||
The disk driver is attached to devices implementing SDSC or SDHC/SDXC commands.
|
||||
There will be other drivers for non-storage (SDIO) cards.
|
||||
|
||||
To help with this, the MMC bus manager provides the device with the information
|
||||
it gathered while initializing the device. According to the commands recognized
|
||||
by the card during the initialization sequence, it's possible to know if it's
|
||||
SDSC, SDHC/SDXC, or something else (SDIO, legacy MMC, etc).
|
||||
|
||||
The disk driver publishes devfs entries in /dev/disk/mmc and implements the
|
||||
usual interface for disk devices. From this point on, the device can be used
|
||||
just like any other mass storage device.
|
||||
|
||||
#### Getting everything loaded
|
||||
|
||||
The device manager is not completely implemented yet. As a result, some
|
||||
decisions about which drivers to load are hardcoded in device\_manager.cpp.
|
||||
|
||||
It has been adjusted to handover SDHCI devices to the MMC bus. Whenever a
|
||||
"disk" device is requested, the MMC busses are searched, which results in
|
||||
loading the SDHCI driver and probing for SD cards. When we get support for
|
||||
other types of SDIO devices, we will need to adjust the device manager to
|
||||
probe the SDHCI bus when these type of devices are requested, too.
|
||||
|
||||
|
||||
### Tasks to be completed
|
||||
|
||||
The SDHCI driver is able to send and receive commands. However it does not
|
||||
handle card insertion and removal interrupts yet, so the card must be already
|
||||
inserted when the driver is loaded.
|
||||
|
||||
As a proof of concept, the initialization sequence has been implemented up
|
||||
until assigning an RCA to a single card (SDHC only).
|
||||
|
||||
Once we get everything in place at the mmc bus level, we can proceed as
|
||||
documented in the GSoC project [third phase outline](https://www.haiku-os.org/blog/krish_iyer/2018-07-12_gsoc_2018_sdhci_mmc_driver_third_phase_plan/).
|
||||
|
||||
If you find it difficult to understand the driver development and it's
|
||||
functioning and role, please refer *docs/develop/kernel/device_manager_introduction.html*
|
||||
@@ -0,0 +1,18 @@
|
||||
INSIDE THE USB STACK
|
||||
==============
|
||||
|
||||
For all of you who have been over my code and thought: "What is this guy doing?", I can firmly respond that I sometimes haven't a clue either. But when I'm actually reviewing my own code, I occassionally get the feeling that I do have a direction I'm persueing. In order to define this direction more, and share you in the fun, I have written this document. It's a rather superficial account (without actually quoting any code), but it should be enough to get you started.
|
||||
|
||||
First of all, it's always good to know that the USB stack is modularised. This means that there is a backend - a module - which connects to a whole range of modules that are in touch with the host controllers (the actual USB hardware). The combination of these modules is what we call the USB stack. The job of the backend (in CVS at /current/src/add-ons/kernel/bus_managers/usb) is to perform generic operations like managing device connects and disconnects, and pushing commands from drivers to the host-controller modules. The host controller modules are in direct contact with the hardware, meaning that they translate actual commands into something the host controller can work with and can transmit over the wires. Additionally, these host controller modules simulate the root hub: they provide a seamless interface for the backend module to communicate with the root hub.
|
||||
|
||||
In the first experiments of my USB stack, there was a special 'C' interface for the host controller modules. This interface was clumsy, because all the objects (the backend is in C++) were constantly harvesting data all over the place because they couldn't simply send references of themselves. The second attempt of the USB stack introduces a libusb.a (the kernel doesn't support shared libraries), which contains the basic structure of the stack, and which is linked in by both the backend and the host controller modules. Instead of having a host_controller_module struct with function pointers, the host controller modules now simply returned an extended 'class Busmanager'. The downside is that whenever the libusb.a is changed, all the host controller modules have to be relinked in order to avoid disasters. (This is also something which prevents me from providing a nice C++ interface for drivers). However, this limitation is much easier to work around than the separate C-interface.
|
||||
|
||||
The basic structure of the stack (and of libusb.a) can be found in the usb_p.h file in the CVS location of the backend. You'll notice a few objects which I'll quickly go over. First of all, there's stack, which is basically a container for the individual Bus managers. The Busmanager class encapsulates a bus manager. The Device class represents a connected device, and the Hub class (inherits Device), manages the communication with the hubs. For the area of communication there are a few classes that are interesting. The Pipe class represents a data pipe. A 'pipe' is more an interface than something that is actually interesting during USB communication. A pipe encapsulates the properties regarding what kind of data is transmitted to where. Each Pipe type (corresponding to the four types of transfer), will be a subclass of Pipe. The objects of Pipe will all be associated with a device. Finally there's the Transfer class. The objects of this class are created by the Pipes, and contain the actual data for the transfers (including references to the callbacks).
|
||||
|
||||
All these classes would be useless, if they weren't interacting with each other. The basic idea of the stack is the following. As soon as the USB bus_manager module is opened by a driver (for the first time), a Stack object is initialized. This object starts looking for host controller modules. Every host controller tries to find and initialize their cards, and if they succeed, they add a BusManager object to the stack. This bus manager object contains an object of the hub class, and the default pipes. The generic backend implementation starts a usb_explore thread, which will poll the status of the hubs and keep the internal administration up to date. As soon as a hub signals that a new device is connected, the Busmanager starts a procedure to connect the device. If it's a hub, a Hub is created, else a Device is created. This device object creates the default pipe, and contains all the data related to it.
|
||||
|
||||
New transfers are initialized by Pipes. The Transfer objects will be created by the Pipe subclasses only, and the ownership of the objects will go to the Busmanager that has to transmit them (that will take care of deletion). The SubmitTransfer function of the Busmanagers are the gate to the actual transfer. What happens is host controller dependent. The implementation of the host controller should take care of finishing a transfer.
|
||||
|
||||
As for closing, this design lacks some objects that correspond to USB objects. For example, there are no special Endpoint objects. At the moment, passing adresses is sufficient, but perhaps it should change in order to complete the design. Also, there is currently no idea how locking should work. Finally, the Stack class currently includes some memory management for usb, however, checking from the specs, only UHCI requires manual scheduling, OHCI and EHCI manage the scheduling and packaging itself. That should move. But at the moment, this design works.
|
||||
|
||||
Finally, this document gives an idea of how it should work. For details: check the USB specs, host controller specs and the code. If anything stays unclear, please comment on my weblog, or e-mail me.
|
||||
Reference in New Issue
Block a user