Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 1 | ========================================================== |
| 2 | How to access I/O mapped memory from within device drivers |
| 3 | ========================================================== |
| 4 | |
| 5 | :Author: Linus |
| 6 | |
| 7 | .. warning:: |
| 8 | |
| 9 | The virt_to_bus() and bus_to_virt() functions have been |
Randy Dunlap | 5872fb9 | 2009-01-29 16:28:02 -0800 | [diff] [blame] | 10 | superseded by the functionality provided by the PCI DMA interface |
Mauro Carvalho Chehab | a822b2e | 2021-06-16 08:27:23 +0200 | [diff] [blame] | 11 | (see Documentation/core-api/dma-api-howto.rst). They continue |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 12 | to be documented below for historical purposes, but new code |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 13 | must not use them. --davidm 00/12/12 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 14 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 15 | :: |
| 16 | |
| 17 | [ This is a mail message in response to a query on IO mapping, thus the |
| 18 | strange format for a "document" ] |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 19 | |
| 20 | The AHA-1542 is a bus-master device, and your patch makes the driver give the |
| 21 | controller the physical address of the buffers, which is correct on x86 |
| 22 | (because all bus master devices see the physical memory mappings directly). |
| 23 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 24 | However, on many setups, there are actually **three** different ways of looking |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 25 | at memory addresses, and in this case we actually want the third, the |
| 26 | so-called "bus address". |
| 27 | |
| 28 | Essentially, the three ways of addressing memory are (this is "real memory", |
| 29 | that is, normal RAM--see later about other details): |
| 30 | |
| 31 | - CPU untranslated. This is the "physical" address. Physical address |
| 32 | 0 is what the CPU sees when it drives zeroes on the memory bus. |
| 33 | |
| 34 | - CPU translated address. This is the "virtual" address, and is |
| 35 | completely internal to the CPU itself with the CPU doing the appropriate |
| 36 | translations into "CPU untranslated". |
| 37 | |
| 38 | - bus address. This is the address of memory as seen by OTHER devices, |
| 39 | not the CPU. Now, in theory there could be many different bus |
| 40 | addresses, with each device seeing memory in some device-specific way, but |
| 41 | happily most hardware designers aren't actually actively trying to make |
| 42 | things any more complex than necessary, so you can assume that all |
| 43 | external hardware sees the memory the same way. |
| 44 | |
| 45 | Now, on normal PCs the bus address is exactly the same as the physical |
| 46 | address, and things are very simple indeed. However, they are that simple |
| 47 | because the memory and the devices share the same address space, and that is |
| 48 | not generally necessarily true on other PCI/ISA setups. |
| 49 | |
| 50 | Now, just as an example, on the PReP (PowerPC Reference Platform), the |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 51 | CPU sees a memory map something like this (this is from memory):: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 52 | |
| 53 | 0-2 GB "real memory" |
| 54 | 2 GB-3 GB "system IO" (inb/out and similar accesses on x86) |
| 55 | 3 GB-4 GB "IO memory" (shared memory over the IO bus) |
| 56 | |
| 57 | Now, that looks simple enough. However, when you look at the same thing from |
| 58 | the viewpoint of the devices, you have the reverse, and the physical memory |
| 59 | address 0 actually shows up as address 2 GB for any IO master. |
| 60 | |
| 61 | So when the CPU wants any bus master to write to physical memory 0, it |
| 62 | has to give the master address 0x80000000 as the memory address. |
| 63 | |
| 64 | So, for example, depending on how the kernel is actually mapped on the |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 65 | PPC, you can end up with a setup like this:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 66 | |
| 67 | physical address: 0 |
| 68 | virtual address: 0xC0000000 |
| 69 | bus address: 0x80000000 |
| 70 | |
| 71 | where all the addresses actually point to the same thing. It's just seen |
| 72 | through different translations.. |
| 73 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 74 | Similarly, on the Alpha, the normal translation is:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 75 | |
| 76 | physical address: 0 |
| 77 | virtual address: 0xfffffc0000000000 |
| 78 | bus address: 0x40000000 |
| 79 | |
| 80 | (but there are also Alphas where the physical address and the bus address |
| 81 | are the same). |
| 82 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 83 | Anyway, the way to look up all these translations, you do:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 84 | |
| 85 | #include <asm/io.h> |
| 86 | |
| 87 | phys_addr = virt_to_phys(virt_addr); |
| 88 | virt_addr = phys_to_virt(phys_addr); |
| 89 | bus_addr = virt_to_bus(virt_addr); |
| 90 | virt_addr = bus_to_virt(bus_addr); |
| 91 | |
| 92 | Now, when do you need these? |
| 93 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 94 | You want the **virtual** address when you are actually going to access that |
| 95 | pointer from the kernel. So you can have something like this:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 96 | |
| 97 | /* |
| 98 | * this is the hardware "mailbox" we use to communicate with |
| 99 | * the controller. The controller sees this directly. |
| 100 | */ |
| 101 | struct mailbox { |
| 102 | __u32 status; |
| 103 | __u32 bufstart; |
| 104 | __u32 buflen; |
| 105 | .. |
| 106 | } mbox; |
| 107 | |
| 108 | unsigned char * retbuffer; |
| 109 | |
| 110 | /* get the address from the controller */ |
| 111 | retbuffer = bus_to_virt(mbox.bufstart); |
| 112 | switch (retbuffer[0]) { |
| 113 | case STATUS_OK: |
| 114 | ... |
| 115 | |
| 116 | on the other hand, you want the bus address when you have a buffer that |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 117 | you want to give to the controller:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 118 | |
| 119 | /* ask the controller to read the sense status into "sense_buffer" */ |
| 120 | mbox.bufstart = virt_to_bus(&sense_buffer); |
| 121 | mbox.buflen = sizeof(sense_buffer); |
| 122 | mbox.status = 0; |
| 123 | notify_controller(&mbox); |
| 124 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 125 | And you generally **never** want to use the physical address, because you can't |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 126 | use that from the CPU (the CPU only uses translated virtual addresses), and |
| 127 | you can't use it from the bus master. |
| 128 | |
| 129 | So why do we care about the physical address at all? We do need the physical |
| 130 | address in some cases, it's just not very often in normal code. The physical |
| 131 | address is needed if you use memory mappings, for example, because the |
| 132 | "remap_pfn_range()" mm function wants the physical address of the memory to |
| 133 | be remapped as measured in units of pages, a.k.a. the pfn (the memory |
| 134 | management layer doesn't know about devices outside the CPU, so it |
| 135 | shouldn't need to know about "bus addresses" etc). |
| 136 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 137 | .. note:: |
| 138 | |
| 139 | The above is only one part of the whole equation. The above |
| 140 | only talks about "real memory", that is, CPU memory (RAM). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 141 | |
| 142 | There is a completely different type of memory too, and that's the "shared |
| 143 | memory" on the PCI or ISA bus. That's generally not RAM (although in the case |
| 144 | of a video graphics card it can be normal DRAM that is just used for a frame |
| 145 | buffer), but can be things like a packet buffer in a network card etc. |
| 146 | |
| 147 | This memory is called "PCI memory" or "shared memory" or "IO memory" or |
| 148 | whatever, and there is only one way to access it: the readb/writeb and |
| 149 | related functions. You should never take the address of such memory, because |
| 150 | there is really nothing you can do with such an address: it's not |
| 151 | conceptually in the same memory space as "real memory" at all, so you cannot |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 152 | just dereference a pointer. (Sadly, on x86 it **is** in the same memory space, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 153 | so on x86 it actually works to just deference a pointer, but it's not |
| 154 | portable). |
| 155 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 156 | For such memory, you can do things like: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 157 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 158 | - reading:: |
| 159 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 160 | /* |
| 161 | * read first 32 bits from ISA memory at 0xC0000, aka |
| 162 | * C000:0000 in DOS terms |
| 163 | */ |
| 164 | unsigned int signature = isa_readl(0xC0000); |
| 165 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 166 | - remapping and writing:: |
| 167 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 168 | /* |
| 169 | * remap framebuffer PCI memory area at 0xFC000000, |
| 170 | * size 1MB, so that we can access it: We can directly |
| 171 | * access only the 640k-1MB area, so anything else |
| 172 | * has to be remapped. |
| 173 | */ |
H Hartley Sweeten | 143724f | 2010-01-01 20:35:41 -0800 | [diff] [blame] | 174 | void __iomem *baseptr = ioremap(0xFC000000, 1024*1024); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 175 | |
| 176 | /* write a 'A' to the offset 10 of the area */ |
| 177 | writeb('A',baseptr+10); |
| 178 | |
| 179 | /* unmap when we unload the driver */ |
| 180 | iounmap(baseptr); |
| 181 | |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 182 | - copying and clearing:: |
| 183 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 184 | /* get the 6-byte Ethernet address at ISA address E000:0040 */ |
| 185 | memcpy_fromio(kernel_buffer, 0xE0040, 6); |
| 186 | /* write a packet to the driver */ |
| 187 | memcpy_toio(0xE1000, skb->data, skb->len); |
| 188 | /* clear the frame buffer */ |
| 189 | memset_io(0xA0000, 0, 0x10000); |
| 190 | |
| 191 | OK, that just about covers the basics of accessing IO portably. Questions? |
| 192 | Comments? You may think that all the above is overly complex, but one day you |
| 193 | might find yourself with a 500 MHz Alpha in front of you, and then you'll be |
| 194 | happy that your driver works ;) |
| 195 | |
| 196 | Note that kernel versions 2.0.x (and earlier) mistakenly called the |
| 197 | ioremap() function "vremap()". ioremap() is the proper name, but I |
| 198 | didn't think straight when I wrote it originally. People who have to |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 199 | support both can do something like:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 200 | |
| 201 | /* support old naming silliness */ |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 202 | #if LINUX_VERSION_CODE < 0x020100 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 203 | #define ioremap vremap |
| 204 | #define iounmap vfree |
| 205 | #endif |
| 206 | |
| 207 | at the top of their source files, and then they can use the right names |
| 208 | even on 2.0.x systems. |
| 209 | |
| 210 | And the above sounds worse than it really is. Most real drivers really |
| 211 | don't do all that complex things (or rather: the complexity is not so |
| 212 | much in the actual IO accesses as in error handling and timeouts etc). |
| 213 | It's generally not hard to fix drivers, and in many cases the code |
Mauro Carvalho Chehab | 38975e9 | 2017-05-14 08:13:48 -0300 | [diff] [blame] | 214 | actually looks better afterwards:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 215 | |
| 216 | unsigned long signature = *(unsigned int *) 0xC0000; |
| 217 | vs |
| 218 | unsigned long signature = readl(0xC0000); |
| 219 | |
| 220 | I think the second version actually is more readable, no? |