AN - 3326 How To Use SAMA5D2 USB Mass Storage Gadget Under Linux 00003326a PDF
AN - 3326 How To Use SAMA5D2 USB Mass Storage Gadget Under Linux 00003326a PDF
Introduction
This application note describes how to get started using the SAMA5D2 USB Mass Storage Gadget under Linux.
The document shows how to simulate a USB Mass Storage Gadget (or “Device”) by using SAMA5D2. The simulation
requires a UDC driver and a Gadget driver. The UDC driver is provided by the Microchip Linux Board Support
Package (BSP); the Gadget driver is contained in the kernel.
Reference Documents
Title Reference Available
SAMA5D2 Series Datasheet DS60001476 https://www.microchip.com/design-centers/32-bit-mpus
SAMA5D27 SOM1 Kit1 User Guide DS50002667 https://www.microchip.com/DevelopmentTools/ProductDetails/
PartNO/ATSAMA5D27-SOM1-EK1
Prerequisites
• Hardware
– PC
– SAMA5D27 SOM1 Evaluation Kit (Part Number: ATSAMA5D27-SOM1-EK1)
– SDCard
– USB cable (Micro-USB to Type-A cable)
• Software
This demo runs on the AT91 Linux platform built by Buildroot. The first step is to set up the AT91 Buildroot
development environment. Refer to the web site: http://www.at91.com/linux4sam/bin/view/Linux4SAM/BuildRoot
Table of Contents
Introduction.....................................................................................................................................................1
Reference Documents....................................................................................................................................1
Prerequisites.................................................................................................................................................. 1
1. Hardware Design.................................................................................................................................... 4
1.1. Interface....................................................................................................................................... 4
1.2. Connection................................................................................................................................... 4
2. Software Design......................................................................................................................................6
2.1. Device Tree.................................................................................................................................. 7
2.2. Kernel........................................................................................................................................... 8
2.3. Rootfs......................................................................................................................................... 10
3. Hands-On.............................................................................................................................................. 11
3.1. Hands-On with Module g_mass_storage.ko...............................................................................11
3.2. Hands-On with Built-In g_mass_storage....................................................................................12
4. Appendix............................................................................................................................................... 14
4.1. How to Add a New Partition to an MMC Card in Buildroot......................................................... 14
4.2. How to Install the genisoimage Command in Buildroot..............................................................14
5. Revision History.................................................................................................................................... 16
5.1. Rev. A - 11/2019.........................................................................................................................16
Customer Support........................................................................................................................................ 17
Legal Notice................................................................................................................................................. 17
Trademarks.................................................................................................................................................. 18
1. Hardware Design
1.1 Interface
VBUS_USBA
R70 USBA_VBUS_5V
PD20
100k
0402 C12
C65 1% R71 0.1uF
200k
20pF 50V
J17 0402
50V 0402
1%
0402
1
VBUS
2 USBA_N
D- USBA_DM
3 USBA_P
D+ USBA_DP
4
ID
5
GND
0
EARTH_USB_A
1.2 Connection
Connect USB-A J17 to the PC using the USB cable (see Prerequisites).
Refer to the following picture.
2. Software Design
The Microchip Linux platform was built using Buildroot with the following configuration:
atmel_sama5d27_som1_ek_mmc_dev_defconfig
The USB Mass Storage Gadget demo works under this default configuration without any adjustment.
The g_mass_storage target in kernel was used to provide a mass storage function and can be built in kernel image or
as a driver module.
Note: As most of the important parameters are passed via module parameters, it is preferable to build the
g_mass_storage target as a driver module; otherwise, bootargs in the U-Boot environment must be modified in order
to pass parameters to g_mass_storage.
The following table describes the g_mass_storage module parameters (source: kernel_dir/Documentation/usb/
massstorage.txt).
Table 2-1. g_mass_storage Module Parameters
Parameter Description
Mass Storage Gadget Specific Module Parameters
This parameter lists paths to files or block devices used for backing storage for each logical unit. There
may be at most FSG_MAX_LUNS (8) LUNs set. If more files are specified, they will be silently ignored.
See also “luns” parameter.
*BEWARE* that if a file is used as a backing storage, it may not be modified by any other process. This is
file=filename[,filename...] because the host assumes the data does not change without its knowledge. It may be read, but (if the
logical unit is writable) due to buffering on the host side, the contents are not well defined.
The size of the logical unit will be rounded down to a full logical block. The logical block size is 2048 bytes
for LUNs simulating CD-ROM, block size of the device if the backing file is a block device, or 512 bytes
otherwise.
This parameter specifies whether each logical unit should be removable. “b” here is either “y”, “Y” or “1” for
true or “n”, “N” or “0” for false.
If this option is set for a logical unit, gadget will accept an “eject” SCSI request (Start/Stop Unit). When it is
sent, the backing file will be closed to simulate ejection and the logical unit will not be mountable by the
host until a new backing file is specified by userspace on the device (see “sysfs entries” section).
If a logical unit is not removable (the default), a backing file must be specified for it with the “file” parameter
as the module is loaded. The same applies if the module is built in, no exceptions.
removable=b[,b...]
The default value of the flag is false, *HOWEVER* it used to be true. This has been changed to better
match File Storage Gadget and because it seems like a saner default after all. Thus to maintain
compatibility with older kernels, it's best to specify the default values. Also, if one relied on old default,
explicit “n” needs to be specified now.
Note that “removable” means the logical unit's medium can be ejected or removed (as is true for a CD-
ROM drive or a card reader). It does *not* mean that the entire gadget can be unplugged from the host;
the proper term for that is “hot-unpluggable”.
cdrom=b[,b...] This parameter specifies whether each logical unit should simulate CD-ROM. The default is false.
This parameter specifies whether each logical unit should be reported as read only. This will prevent host
from modifying the backing files.
Note that if this flag for given logical unit is false but the backing file could not be opened in read/write
ro=b[,b...] mode, the gadget will fall back to read only mode anyway.
The default value for non-CD-ROM logical units is false; for logical units simulating CD-ROM it is forced to
true.
...........continued
Parameter Description
This parameter specifies whether FUA flag should be ignored in SCSI Write10 and Write12 commands
sent to given logical units.
MS Windows mounts removable storage in “Removal optimised mode” by default. All the writes to the
media are synchronous, which is achieved by setting the FUA (Force Unit Access) bit in SCSI Write(10,12)
nofua=b[,b...] commands. This forces each write to wait until the data has actually been written out and prevents I/O
requests aggregation in block layer dramatically decreasing performance.
Note that this may mean that if the device is powered from USB and the user unplugs the device without
unmounting it first (which at least some Windows users do), the data may be lost.
The default value is false.
This parameter specifies the number of logical units the gadget will have. It is limited by FSG_MAX_LUNS
(8) and higher values will be capped.
If this parameter is provided, and the number of files specified in “file” argument is greater than the value of
luns=N “luns”, all excess files will be ignored.
If this parameter is not present, the number of logical units will be deduced from the number of files
specified in the “file” parameter. If the file parameter is missing as well, one is assumed.
Specifies whether the gadget is allowed to halt bulk endpoints. The default is determined according to the
stall=b type of USB device controller, but usually true.
0xfc02c000 0x400>;
// definition for ctrl memory region, base address 0xfc02c000, size 0x400
ep@0 {
// definition for usb end point
reg = <0>;
atmel,fifo-size = <64>;
atmel,nb-banks = <1>;
};
ep@1 {
reg = <1>;
atmel,fifo-size = <1024>;
atmel,nb-banks = <3>;
atmel,can-dma;
atmel,can-isoc;
};
usb0: gadget@300000 {
atmel,vbus-gpio = <&pioA PIN_PD20 GPIO_ACTIVE_HIGH>;
// USB vbus pin definition
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_usba_vbus>;
// definition for usb0 pins
status = "okay";
// replace status’s property with “okay”, enable usb0 device
};
2.2 Kernel
• Action: no need to change
• Location: buildroot-at91/output/build/linux-linux4sam_6.0/
• Defconfig: sama5_defconfig
• Driver files:
– drivers/usb/gadget/udc/atmel_usba_udc.c
– drivers/usb/gadget/function/f_mass_storage.c
– drivers/usb/gadget/legacy/mass_storage.c
Check the kernel configuration for the USB mass storage gadget function:
user@at91:~/buildroot-at91$ make linux-menuconfig
Device Drivers > USB support > USB Gadget Support > USB Peripheral Controller > Atmel USBA
Driver for the UDPHS (USB Device Port High Speed) controller.
<M> was used for this driver, and this driver module will be inserted into the kernel automatically by udev once usb0,
in the device tree, is registered.
With the default setting, this item has been selected.
Device Drivers > USB support > USB Gadget Support > USB Gadget precomposed configurations
Select the “USB Gadget precomposed configurations” item. All supported gadget devices will be listed.
Device Drivers > USB support > USB Gadget Support > Mass Storage Gadget
Select “Mass Storage Gadget” with <M>. It will be built as a driver module.
It can be seen that some other gadget device drivers were selected with the default setting. After a successful build,
all driver module files will be stored in rootfs and these modules can be dynamically inserted and removed at runtime
according to the application requirements.
2.3 Rootfs
• Action: no need to change
• Location: buildroot-at91/output/images/rootfs.tar
3. Hands-On
Some important parameters must be passed during g_mass_storage initialization. The parameter “removable” must
be passed by updating bootargs. See 3.2.1 Using sysfs to Interact with g_mass_storage.
Other parameters can be passed to g_mass_storage via the sysfs interface. Use the following command to insert
storage medium “/dev/mmcblk0p1” into the USB mass storage drive:
# cd /sys/devices/platform/ahb/300000.gadget/gadget/lun0
# ls
file nofua power ro uevent
# echo /dev/mmcblk0p1 > file
4. Appendix
2. Rebuild Buildroot:
user@at91:~/buildroot-at91$ make
5. Revision History
Customer Support
Users of Microchip products can receive assistance through several channels:
• Distributor or Representative
• Local Sales Office
• Embedded Solutions Engineer (ESE)
• Technical Support
Customers should contact their distributor, representative or ESE for support. Local sales offices are also available to
help customers. A listing of sales offices and locations is included in this document.
Technical support is available through the website at: http://www.microchip.com/support
Legal Notice
Information contained in this publication regarding device applications and the like is provided only for your
convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with
Trademarks
The Microchip name and logo, the Microchip logo, Adaptec, AnyRate, AVR, AVR logo, AVR Freaks, BesTime,
BitCloud, chipKIT, chipKIT logo, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, HELDO, IGLOO, JukeBlox,
KeeLoq, Kleer, LANCheck, LinkMD, maXStylus, maXTouch, MediaLB, megaAVR, Microsemi, Microsemi logo, MOST,
MOST logo, MPLAB, OptoLyzer, PackeTime, PIC, picoPower, PICSTART, PIC32 logo, PolarFire, Prochip Designer,
QTouch, SAM-BA, SenGenuity, SpyNIC, SST, SST Logo, SuperFlash, Symmetricom, SyncServer, Tachyon,
TempTrackr, TimeSource, tinyAVR, UNI/O, Vectron, and XMEGA are registered trademarks of Microchip Technology
Incorporated in the U.S.A. and other countries.
APT, ClockWorks, The Embedded Control Solutions Company, EtherSynch, FlashTec, Hyper Speed Control,
HyperLight Load, IntelliMOS, Libero, motorBench, mTouch, Powermite 3, Precision Edge, ProASIC, ProASIC Plus,
ProASIC Plus logo, Quiet-Wire, SmartFusion, SyncWorld, Temux, TimeCesium, TimeHub, TimePictra, TimeProvider,
Vite, WinPath, and ZL are registered trademarks of Microchip Technology Incorporated in the U.S.A.
Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BlueSky, BodyCom,
CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dsPICDEM,
dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP,
INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, memBrain, Mindi, MiWi, MPASM, MPF,
MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM,
PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad
I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense,
ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A.
and other countries.
SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.
The Adaptec logo, Frequency on Demand, Silicon Storage Technology, and Symmcom are registered trademarks of
Microchip Technology Inc. in other countries.
GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip
Technology Inc., in other countries.
All other trademarks mentioned herein are property of their respective companies.
© 2019, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.
ISBN: 978-1-5224-5301-7
AMBA, Arm, Arm7, Arm7TDMI, Arm9, Arm11, Artisan, big.LITTLE, Cordio, CoreLink, CoreSight, Cortex, DesignStart,
DynamIQ, Jazelle, Keil, Mali, Mbed, Mbed Enabled, NEON, POP, RealView, SecurCore, Socrates, Thumb,
TrustZone, ULINK, ULINK2, ULINK-ME, ULINK-PLUS, ULINKpro, µVision, Versatile are trademarks or registered
trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
For information regarding Microchip’s Quality Management Systems, please visit http://www.microchip.com/quality.